If none of these FAQs seems to address your problem, look at the Upstream Bugs page.
1. First, check that the GPS has power. If it is a USB device, it needs to be cabled to a USB port to have power. All Bluetooth GPSes and some serial GPSes are powered by an on-board battery; check that the battery is present and charged. The GPS may have an on-off switch which needs to be in the 'on' position.
2. Most GPSes have a power-on LED; it should be continuously on or blinking once a second. If it is continuously off, your GPS is dead or disconnected. Check that it has power.
3. For anything other than a serial (RS232) device, there should be a discovery utility that allows you to check that the device is connected.
3a. For a USB device, run
"lsusb" before and after
connecting your GPS; after, you should see an additional line
indicating a new device. Expect the new line to describe a
serial-to-USB adapter chip, often (but not always) the Prolific
Technology PL2303. Then run "dmesg", looking for a message indicating
a new USB device of that kind and giving you the device path -
/dev/ttyUSBn for some number n.
3b. If your receiver lists in lsusb(1) but doesn't show up as a ttyUSBx device, don't lose hope. It might be a ttyACM device, probably /dev/ttyACM0; some receivers, including for example the u-blox EVK 6H evaluation kit, announce themselves as USB modems.
3c. For a Bluetooth device, see our Bluetooth instructions.
4. If you have installed a GPSD binary package on a Linux system and
are using a USB GPS, you should not need to start gpsd manually,
because the hotplug system will have done it for you. You should be
able to start a test client (such as
and watch it report fixes.
5. If your test client fails to run, a good test to try is to,
after stopping any instances of gpsd that are running
killall gpsd ),
gpsmon on the device (give it the device path as an
argument). If yours reports no data at all, you probably have some
low-level system problem with serial or USB that you'll need to fix
gpsd will operate.
6. USB GPSes actually emulate RS232 serial using converter chips. Under Linux, the usbserial kernel module must be loaded for correct operation of this class of device. Normally this module load should happen automatically when the device activates, but if you don't receive data check for it with lsmod(1).
On Linux systems with module autoloading disabled or misconfigured,
it is possible you may need to load the module manually with a command
sudo modprobe usbserial vendor=0x1a86
product=0x7523. Do not copy those hex numbers slavishly, they
are examples. To get the right numbers, you will need to dig up the
vendor and product ID of your USB-serial converter device.
For more detailed troubleshooting instructions, see the Troubleshooting Guide.
GPSD's support for the NMEA protocol is mature and stable. If the specification for your receiver says "NMEA 0183" (maybe with a version 2.x or 3.x qualifier) it should just work.
Beware of receivers that do not say "NMEA" somewhere in the specification; while it may indicate that the receiver only uses a binary protocol, it often means that the receiver cannot be used as data source for a computer, as is usually the case with car navigation devices.
We also support many proprietary protocols, in case your receiver
doesn't emit NMEA. Datasheets often indicate which chip the receiver
is based on, for example a NavCorp NX666. Check to see if other
NavCorp receivers are listed, either as a vendor or a
chipset. Compare this with the output of
gpsd -l which
will list the protocols compiled into gpsd. If your receiver doesn't
support NMEA and we don't have a special driver for the chipset, talk
to us. But it'll probably just work.
Assuming the receiver has a USB interface, do a web search to see
if someone has tried it with linux already, eg. "
linux". Search for the product and "driver install" to find
instructions on installing Windows drivers for the product - these
often hint at which bridge chip is used, if the specifications don't
A GPS receiver claiming Macintosh compatibility is usually based on one of the common bridge chips from FTDI, Prolific or Silicon Laboratories. These will just work.
Yes, Android 4.0 and later versions use gpsd to interpret the data stream from the onboard GPS. No, the battery drain is not actually due to a GPSD bug or design error.
You probably have a badly-written or buggy app installed that is running in background, keeping gpsd awake by keeping a client session to it constantly open; this can happen if the app is using "Fine Location" rather than computing its location the cheaper way using cell-tower signal strengths ("Coarse Location"). What you need to do is identify that app, and decide if you wish to remove it.
On the Samsung Galaxy SIII, vendor firmware provides a "Remote Location" service with a similar bug. You can disable this through Settings. See this blog post for a fix.
Garmin binary protocol is weird enough that it can't be handled through the regular serial-device layer of Linux - you couldn't tell where the packet boundaries are. To deal with it, you need a special loadable kernel module called 'garmin_gps'.
The most common cause of problems with these devices is that the module is failing to load as it should when the Garmin USB ID is recognized. Here is a typical resolution:
After several more days of effort I did eventually get it to work [under Ubuntu 12.4]. It turned out that garmin_gps was on the black list and this needed to be commented out. I then had to 'sudo apt-get install gps-clients gpsbabel' and a 'sudo modprobe garmin_gps' and all was working.
On the BSDs and Mac OS X, you're out of luck. As of April 2013 we don't know of any shim that makes USB Garmins work on these.
Sadly, no. There are both hardware and software barriers to this.
Using AGPS would requires picking up and interpreting information broadcast by cellphone towers, so it would at minimum need another receiver (separate from the GPS mouse) operating in those frequency bands. Of course, a cellphone has one of those built in. Standalone GPS sensors don't.
There's another level of the problem, too. Supposing we had the right sort of receiver, AGPS systems are carrier-dependent. As far as we know there aren't any published standards for the format of the corrections. So even if we had the signals, GPSD couldn't know what to do with them.
The Raspberry Pi has no real-time clock. Without this, the GPS may not return sufficient information to for GPSD to pin down which GPS clock rollover period you are in. If you set the system clock to some date in the current year before launching gpsd you will see correct time reports.
Note: Because we have been informed that some people are insane about this, we shall state the obvious: we welcome security-related bug reports and will not sue people who send them to us. If your report includes sensitive information or discloses an exploit, please email a maintainer rather than letting it all hang out on the public bugtracker. We will fix such bugs promptly.
When you have a problem with gpsd, here are some steps you can take to help get your bug resolved as quickly as possible.
1. Read this whole FAQ first
First, read this whole FAQ before reporting apparent misbehavior as a bug. You may find a solution here.
2. Make sure it's not a problem with your toolchain or OS
See our page on upstream bugs.
3. Make sure it's not a problem in your client software
Make sure it is a real gpsd bug and not a problem with your client software. A good way to do this is to run your client and a gpsd test client (cgps or xgps) side by side. If the gpsd test client seems to report good numbers but your client does not, you have a client problem. If cgps or xgps reports the same sort of bad numbers as your client, you have a real
4. Check the latest version of
gpsdfor the bug.
If you are using an old version of
gpsd, it is possible your bug has already been fixed. Download the latest public version from the download page and test it. To be really helpful, check out git head and test that. We don't mind getting reports that say "I saw version foo had the following bug, but you've fixed it."
5. Capture a log that triggers the problem
If we can reproduce your gpsd problem, we can usually fix it very rapidly. If we can't reproduce it, you might get lucky or you might not — and we try hard, but all too often the result is 'not'.
Therefore the most important step you can take is to capture a log of some receiver output that reproduces the bug;
gpspipe -R -n 100will help you.
6. Trim the capture log that reproduces the problem
Your next step should be to feed the log you just captured to a
gpsfaketo verify that the log does in fact reproduce the bug.
Once you have the log, trim it to the smallest span of data that reproduces the bug. A systematic way to do this is to cut the log in half at the middle and test each half. If one half doesn't reproduce the bug but the other does, throw away the half that doesn't. Repeat this procedure on each half that tickles the bug until you can't make it any smaller. Then send us that.
If possible, use the -l option of gpsfake to pin down the sentence or packet that produces the bug, and tell us that.
7. Look at
gpsdlog output to see if it gives you a clue
You may get a better handle on your problem by running gpsd in foreground (-N option) with the -D option set to a high level (-D 5 is often good). If the transcript has anything that looks like a clue in it, send it along with your bug report. When in doubt about whether it holds a clue, send it.
One of the things this should tell you, if the chip reports it at all, is the firmware version. You will want that for your report.
8. Annotate the capture log and send us a copy
Annotating the log you send by adding a header is helpful. Your logfile should consist of an identifying header followed by an untouched and unencoded dump of receiver data, whether NMEA, binary or a mixture. The header should consist of text lines beginning with # and ending with LF. Here is the beginning of one log file from the gpsd regressions:# Name: Magellan eXplorist 210 # Chipset: unknown # Submitter: "Paul B van den Berg" <email@example.com> # Date: 2006-05-26 # Location: Groningen, NL, 53.2N 6.6E # # mode V2.1 GSA # Lines up to but not including the first GPGLL are # `cat /dev/ttyACM0` at startup # Following lines are # `cat /dev/ttyACM0` stationary $GPGSV,3,1,00,,,,,,,,,,,,,,,,*7B $GPGSV,3,2,00,,,,,,,,,,,,,,,,*78 $GPGSV,3,3,00,,,,,,,,,,,,,,,,*79 $PMGNST,01.75,3,F,816,11.1,+00000,20*5E $GPGSV,3,1,00,,,,,,,,,,,,,,,,*7B $GPGSV,3,2,00,,,,,,,,,,,,,,,,*78 $GPGSV,3,3,00,,,,,,,,,,,,,,,,*79 $PMGNST,01.75,3,F,816,11.1,+00000,20*5E $GPGSV,3,1,00,,,,,,,,,,,,,,,,*7B $GPGSV,3,2,00,,,,,,,,,,,,,,,,*78 $GPGSV,3,3,00,,,,,,,,,,,,,,,,*79 $PMGNST,01.75,3,F,822,11.2,+00000,20*5A $GPGSV,3,1,00,,,,,,,,,,,,,,,,*7B $GPGSV,3,2,00,,,,,,,,,,,,,,,,*78 $GPGSV,3,3,00,,,,,,,,,,,,,,,,*79 $PMGNST,01.75,3,F,822,11.2,+00000,20*5A $GPGSV,3,1,12,09,76,287,,17,38,073,36,26,34,163,,05,33,230,*72 $GPGSV,3,2,12,29,27,161,,18,24,256,,22,24,299,,28,11,055,*73 $GPGSV,3,3,12,14,08,319,,11,03,017,,30,02,232,,24,00,084,*71 $PMGNST,01.75,3,F,822,11.2,-00673,20*5E $GPGLL,5313.2228,N,00634.4228,E,200619.295,A*35 $GPGGA,200619.30,5313.2228,N,00634.4228,E,1,05,2.6,00000,M,,,,*2C $GPRMC,200619.30,A,5313.2228,N,00634.4228,E,00.0,000.0,200506,00,W*59 $GPGSA,A,3,26,05,22,09,18,,,,,,,,05.1,02.6,04.4*03 $GPGSV,3,1,10,09,78,288,39,17,38,071,,05,34,230,45,26,33,163,39*77 $GPGSV,3,2,10,29,26,162,,18,24,255,42,22,24,298,44,28,10,056,*75 $GPGSV,3,3,10,14,09,319,,11,03,016,,136,27,157,,124,28,162,*71
The way to fill in the Name, Submitter, and Date headers should be pretty obvious.
Chipset should include the name and (if possible) model and/or firmware revision of the chipset in the GPS.
Please also include a Location header giving your city, state/province, country code, and a rough latitude/longitude.
A log file is most useful when it contains (a) some sentences generated when the GPS has no fix, (b) some sentences representing a fix with the GPS stationary, and (c) some sentences representing a fix with the GPS moving.
If you have notes or comments on the logfile or the GPS, or any additional information you think might be helpful, add them as additional # comments (not containing a colon) after these headers. The test machinery that interprets the headers will ignore these and any empty comment lines.
9. If it's a dual-mode GPS, see if the problem reproduces in NMEA mode
If you're using a SiRF, Evermore, iTalk or u-blox GPS in binary mode (which you can tell from the -D 4 output), switch back to NMEA mode using the N command (or a vendor-provided tool) and see if the bug is still reproducible.
10. If your bug core-dumps gpsd, send us a stack trace.
Though it happens seldom (we've had only 3 such reports since about mid-2005), badly-formed input from a device with poor standards compliance has been known to core-dump gpsd. If your gpsd has core-dumped, try to use gdb or whatever your local symbolic debugger is to generate a stack trace ("bt full") of the crash, and send us that.
Very occasionally we have also received reports of core dumps in gpsfake and gpson. A stack trace is also useful in those cases.
A good technique in all such cases is to try to reproduce the bug by feeding a log with the bad packet in it to gpsdecode. This utility exercises the same packet decoders as gpsd/gpsfake/gpsmon but without involving nearly as much other code. If you can send a test log that crashes gpsdecode, you can expect the bug to be fixed very quickly.
11. Try to determine what release introduced the bug
If you have upgraded from a previous version of
gpsd, and the upgrade broke something that was working previously, the most useful thing you can do is pin down the release in which the bug was introduced.
How efficiently you can do this depends on whether or not you have a client for the git version control system. If you don't, all you can do is download and test named releases. If you do, you can pin down the exact change that introduced the bug. The latter is far more helpful to us and will get your bug fixed faster, so we'll describe that procedure here.
Follow these instructions to clone a copy of the source repository.
Use git bisect to locate the exact revision that introduced your bug. This will happen very quickly, as the number of tests required will be the log to the base 2 of the number of revisions in your original span. Even if there are (say) 500 revisions in the span you should only require 9 tests to nail down the exact change in question.
12. Include the vendor, mode, and firmware version in your report.
Always include with your bug report the receiver vendor and model. Try to include the firmware version as well. This should be in your xgps display if your device makes it available; in a form field before 2.35, or as the window title in 2.35 and later. If the ID string is too long to fit, let the daemon run for a few minutes and issue an "I" command to it. Alternatively, running the daemon at -D 4 may reveal the version.
In 3.10 and newer versions, running gpsctrl with your GPS's device path as an argument will produce a report that includes both the GPS type and subtype, if that information is available at all.
13. Report it on the GPSD bugtracker
There is a GPSD bug tracker. Use that. If your bug narrative does not fit the tracker template well and you've done these data-gathering steps, it's acceptable to send an email report to the GPSD developers' list.
If you are submitting a code patch or a technically detailed bug report, write the GPSD developers' list (and see the previous entry on how to report bugs).
Please do not write to the dev list unless you are willing to actively work with our developers on a solution. If you are non-technical and confused, the GPSD users' list will be more appropriate.
GPSD developers are often, though not predictably, available in real time on IRC.
Commercial users: senior GPSD developers are available for contract engagements at reasonable rates. If you have a hard problem or a tight deadline or both, request an engagement via the dev list or IRC. We're professionals and experts and we deliver results.
Most of GPSD is under the permissive BSD-2-Clause license. Some portions are under other permissive licenses, including the MIT/X license and the ISC license.
Most of GPSD is "Copyright The GPSD Project". Some portions also have copyrights from the original contributors or original sources. This project follows the guidance from The Linux Foundation: Copyright Notices in Open Source Software Projects. Notice there is no need for "(C)", dates, or other decorations.
Yes, GPSD code can be used in commercial and for-profit deployments without restrictions.
If you use GPSD to make money, please show some concern for the project's sustainability; leave a remittance at Patreon.
On a Linux machine, the
gpsd daemon normally takes
between 0.1 and 0.6 seconds to handshake with your hardware, but this can
vary widely. After
that you will receive GPS reports within a second of when the sensor
issues them. GPSD itself adds almost nomeasurable latency, but RS-232 transmission time to
gpsd can be more significant; you can cut this time by
increasing the serial port speed (baud rate).
Longer handshake delays have been reported from other platforms.
Under OpenBSD, time to handshake with some binary GPSes (including
SiRFs) can be up to two minutes. This seems to reflect some bad
interaction between the autobauding code in
gpsd and the
operating system's tty layer; when
gpsd is compiled to
use a fixed port speed, handshake times drop to a fraction of a
If you are starting a GPS for the first time, or after it has been powered off for more than a few weeks, this is a 'cold start'; it needs to get a new satellite almanac to do its job. The satellites broadcast this information very slowly (at 50bps) on a fixed schedule, and it can take up to 20 minutes.
Without an almanac, your GPS has trouble finding the satellites. The satellites broadcast on a known frequency, but they are moving, and that gets shifted all over the place by the Doppler effect. ("All over" means a big shift relative to the bandwidth of the signal.)
If you have a recent almanac and you know the date/time and location, then you can compute the Doppler and look in the right frequency and find the satellites quickly. In this context, "find" means hearing a signal at an expected frequency. If you don't hear anything where you expect it, then you get to check nearby frequencies. If you don't find anything nearby, you get to give up and start searching the whole Doppler range. This is the difference between warm start and cold start.
Once you do see one or more satellites, you can figure out the date/time and location and after a while get a new almanac. This will be stored in non-volatile memory in your devices and make subsequent satellite acquisitions faster, until it gets stale.
Warm start on a modern GPS with a good skyview (4 or more sats visible) normally takes about 30 seconds. (Vendor spec sheets fib by quoting this time only, leaving out the cold-start lag to fetch almanac.) If it's taking longer, the first thing to suspect is that your skyview is poor. Especially if you're indoors.
The best advice is: go outside and be patient for a few minutes.
Your GPS may have dropped its leap-second offset. You can tell you have this problem if your sentence timestamps look wrong at startup. Wait 20 minutes or so; the lag should go away, as the almanac is updated.
GPS satellites broadcast time using a clock without a leap-second correction. They broadcast a leap-second correction once each complete reporting cycle along with the satellite almanac; it's up to the GPS firmware to add that correction to the time it puts in reports. If your GPS has forgotten the current correction, you'll have to wait until an updated almanac is downloaded (should be less than 20 minutes).
GPSes are supposed to retain the leap-second correction along with the last fix in NVRAM when they power down, but we've observed that many seem prone to occasionally drop this information. All you can do is wait for the problem to resolve itself.
SiRF-based GPSes have a more specific timelag problem. 4800 is just a bit too slow for SiRF binary at full flood; the device can actually fail to ship all its reports before the next once-per-second fix, producing an accumulating stall. The symptom of this is sentence times that look right at startup but gradually fall behind clock time. To fix this, bump your speed to 9600 or higher.
This can happen if (a) there has been a recent leap-second adjustment, (b) you have a version of GPSD that was built before the adjustment, and (c) your GPS doesn't ship the current leap-second offset in a form GPSD can see. If this happens, GPSD will fall back to a compiled-in default that is off by one
Some SiRFs have a particularly insidious version of this. They are supposed to ship a MID52 sentence (which GPSD knows how to interpret) containing the current leap-second offset. But there is at least one firmware revision that ships a damaged version of MID52 with a garbled start sequence or a zero length field. GPSD cannot handle this.
The bad revision is 2.3.2-GSW2-2.05.024-C1Prod1.1; there may be others. Suspect this if you have persistent off-by-one errors. If you are able to identify other bad firmware versions, please let us know about it.
If your problem is wildly fluctuating speed reports on a SiRF,
switch on static navigation mode using the
M command in
gpsmon. Static navigation mode will freeze your position
if your speed is below 1.2 m/s for three seconds, and will begin
updating your position again when speed exceeds 1.4 m/s. This
prevents multipath, weak signals, or poor constellation geometry
from dragging your solutions around too much. Other receivers may
suffer the same problem and may have a similar solution.
Use an external antenna, and place the sensor (and/or antenna) properly.
A good antenna can help, especially if you're using PPS as a time reference. It should be particularly helpful for reducing timing jitter.
One common error is to place the GPS or antenna as high as possible. This will increase multipath effects due to signal bounce from the ground or water, which can cause the GPS to mistake its position and the time signal. The correct location for a boat GPS antenna is on the gunwale rail or pushpit rail, close to the water and as far from the mast as possible (to reduce signal bounce from the mast). If you're outside or in a fixed location, put the GPS antenna as far from buildings as possible, and on the ground. If you're in a car, don't put the GPS antenna on the roof, put it on the towbar, far forward on the dashboard, or some similar location.
If you're driving in a heavily built up area, you're going to get signal bounce off buildings and reduced accuracy. That's just how the physics works. Note, however, that as your velocity goes up it becomes easier for the convergence filters in your GPS to spot and discard delayed signal, so multipath effects are proportionally less important in fast-moving vehicles.
If you're using
gpsd with software that plots your
position on a map, and you seem to be getting latitude/longitude that
is at a fixed offset from reality, it is possible the base datum of
the map is something other than the WGS84 GPS uses. A
frequently-occurring case of this is older maps in the United States
based on NAD27 (e.g., USGS topo maps); you may see a displacement of
as much as 100-150m with respect to WGS84. While modern datums (e.g.,
NAD83) are almost all very close to WGS84, typically each area of
world has an older datum that only agrees at the 100m level.
All the measures you'd take to improve fix accuracy will help. Time referencing at accuracies below 0.01sec has its own set of issues related to latency in your sensor and computer.
There is now a GPSD Time Service HOWTO that gives detailed setup instructions.
The earliest SBAS systems were WAAS (North America) and EGNOS (Europe). Multiple such systems exist, covering Japan (MSAS), India (GAGAN), etc, with more being deployed.
In your skyview, look for GPS sats with numbers 120 and above; those are the Space Based Augmentation System (SBAS) birds. For U.S. users 138 is the most likely PRN to show up. If your GPS receiver can see them at all, it can probably use them for correction when you're within the coverage area of a SBAS. But you can't be sure of this unless they're marked as part of the satellite set for a fix. On the other hand, some receivers may use them without marking the SBAS satellites as part of the fix set. Vendor documentation in this area tends to be murky or nonexistent.
If your receiver emits the NMEA GGA sentence, look at field 6 right after the E or W qualifier for the latitude. This is the GPS fix quality indicator field. 2 indicates that the receiver is getting and using differential-GPS corrections. On a consumer-grade GPS this usually means SBAS is in use.
Unfortunately, the mere presence of "WAAS" in your receiver's feature list is not a guarantee that WAAS is actually supported. This feature causes significant additional power usage, and OEMs sometimes condition it out of their firmware builds without documenting that fact.
It has been found that while SiRF-II chips generally had WAAS working, SiRF-III support varies by firmware level.
Your GNSS receiver uses interative math to compute its position. That needs then be encoded into variable length NMEA sentences. Plus there are a variable number of NMEA sentences every fix epoch. Then they all need to fit through a slow serial line.
If you want to reduce your TOFF jitter, then use a faster serial port rate, and use a fixed length binary protocol. To make TOFF much less important, use PPS.
This is a gpsdrive bug, as you can verify by running
xgps alongside it.
Your Kismet configuration has to include the setting "gps=true" This is a surprisingly easy detail to forget.
gpsd code is designed to be autoconfiguring for both
static and hot-plugged devices. The
gpsd command line
options are only for problem solving or odd configurations.
One common problem is GNSS receivers that operate over Bluetooth.
Changing the speed of these is difficult to impossible. Some go
catatonic if you try to change the serial port speed rate, which is
why we have a -b option that prevents
gpsd from trying to
configure the GPSes it talks to.
Another problem is that some systems may have long autobaud detection
times, or be set to impossible to detect framing, like 8O1.
On most systems, simply set the speed and framing before calling
gpsd will try those settings first.
This works for both devices specified on the
line and those hot-plugged with
Accordingly, you can short-circuit the autobaud if you use stty(1) to set the bit rate just before starting gpsd. For example, suppose you know that your GPS is on serial port 0 and operates at a fixed bps of 54600. You can set that up like this:
stty -F /dev/ttyS0 speed 54600 gpsd -n /dev/ttyS0
If you have a Trimble that needs 115200 and 8O1, do this:
stty -F /dev/ttyS0 speed 115200 parodd gpsd -n /dev/ttyS0
If you only have one device connected to
that device is specified on the command line, then you can instead
specify the speed with the -s [SPEED] option and/or the framing
with the -f [FRAMING] option.
For more details and discussion about autobaud refer to the Hacker's Guide.
Most USB devices have a defined device class - mass storage, video, hub, and human interface device are three of the more common ones. Using GPSD will never interfere with such devices, nor will they interfere with GPSD.
Unfortunately, there is no device class for USB GPSes. Nor is there a device class for USB-to-serial adapter chips. Both are assigned the catch-all class 0xFF, "Vendor Specific". Almost every USB GPS we've ever seen consists of a GPS module with TTL-level RS232 outputs connected to an RS232-to-USB adapter chip, and presents the class ID 0xFF to your USB subsystem. The only exceptions we know of are some u-blox modules that pretend to be USB modems.
When you install GPSD, it puts in place rules that watch for
hotplug activation events from devices that might be GPSes. When such
a hotplug event happens, a
gpsd instance is started (if
one is not already running) and puts a copy of the device path in an
internal stash list. Later, if a client application requests GPS data,
gpsd will try to read from the device, and discard it
from the stash list if it is not emitting data that
GPSD's notion of "might be a GPS" depends on the fact that all USB GPSes are made with one of a small number of USB-to-serial adapter chips, the most common of which is the Prolific Logic 2303. GPSD's hotplug rules expect that anything exhibiting the USB vendor:product ID pair of one of these chips will be a GPS.
A problem can arise if you have other devices connected to your
system through one of these specific adaptor chips. When these
activate, the GPSD hotplug rules will believe they are GPSes, and
gpsd will try to read from them when a GPS-ware client
application requests data. We've had reports of this happening with
USB modems and various microcontroller kits. It's not a problem we can
solve with clever programming, the devices simply don't yield
enough information about themselves to avoid conflicts.
gpsd at 3.1 and later versions checks
each serial and USB device after opening it to see if any other
process has that device open; if so, it's dropped. This should at
least keep GPSD from usurping data sources belonging to other service
Note that GPSD never tries to configure USB devices until it has identified them as sensors of a known type. Also, it tries to open with TIOCEXCL and thus will not open devices that another process already has open. So the worst case is a race between GPSD and another process to open a device not in use, in which the other process's open fails.
If this sort of conflict becomes a problem, you can work around
it by disabling the GPSD hotplug rules. Unfortunately, this means
you will have to start
gpsd manually with a device-path
argument when you want to use a GPS.
gpsd, is designed to run light so it can be
used in low-power embedded-systems deployments. Data throughput from GPSes
and other navigational sensors is low and tends to be concentrated in bursts
at about one-second intervals; accordingly,
gpsd spends most
of its time simply waiting in select(2) at effectively zero CPU cost. Even
with a client session and a GPS active, we have measured gpsd's CPU load
at steadily less than 1% on a low-power, low-speed ARM SBC.
Occasionally we get a bug report from a user who says a USB port
locks up or becomes unavailable after
gpsd has closed it.
Such problems may persist until the USB port is unplugged and
replugged, or until all devices in that root hub are unplugged and
replugged, or even until a reboot.
This is not a GPSD bug. Bugs in the serial-device layer of your operating system, tickled by gpsd's unusual autobauding loop and serial-parameter changes, can cause problems like this. They may be driver-specific bugs, or they may be due to bad interactions between ioctl() and select() in the kernel's generic tty code. Bugs in the USB chipset on your motherboard or in a hub can do it, too.
Here are some possible fixes:
gpsdstresses chipsets and drivers in unusual ways, which is why these sorts of bugs show up more often under
gpsdthan most other USB-using software. The first thing to try is to suppress the autobauding loop.
When you have had such a problem with
gpsd, and are
able to work around it or fix it, please inform us so we can
improve this FAQ.
gpsdsometimes stops responding overnight
At one point in the development of
gpsd we got a
report of the daemon ceasing to respond to queries when run for
more than a day or so; the user, quite reasonably, suspected some sort
of resource leak in the daemon. On the other hand, other users reported
good operation over much longer periods with the same version of
the software. That suggests a bug at the level of the user's operating
system or local site configuration.
Nevertheless, the possibility of a resource-leak bug alarmed us enough that after 2.26 one of us (ESR) built an entire test framework for auditing the code's dynamic behavior and used it to apply Valgrind. You can look at the resulting script, valgrind-audit, in the source distribution. This turned up a couple of minor leaks, but nothing sufficient to explain the report.
One of our senior developers, Rob Janssen, has seen
gpsd interact badly with overnight backups, pushing the
system load average through the roof. He says: "when you copy many
gigabytes of data from disk to disk, the [Linux] kernel's buffer
management goes completely haywire. [...] I think this is caused both
by allocation of many buffers for reading files, and by accumulation
of many dirty buffers that still have to be written. At some point,
programs like gpsd (but also all interactive programs and the X
display manager) come to a complete standstill while the system is
swapping like mad."
If Rob's analysis is correct,
gpsd is a canary in a
coal mine. If your
gpsd locks up after a long period of
operation, you should look at your logs and see if you can connect the
point at which it stopped responding to some kind of resource crisis
brought on by lots of I/O activity.
Another thing to try is running
gpsd under Valgrind overnight
and seeing if it reports any leaks.
gpsdprotocol rather than parsing raw NMEA?
Some applications that use
gpsd start raw mode
and parse the NMEA directly. This is not a good idea.
One problem with raw mode is that NMEA is a poorly specified standard. There are, for example, two different and incompatible variants of GPVTG. Another issue is that implementations vary as to whether they leave fields they don't supply empty or fill them in with a special value such as 0.0. Interpretation of the different NMEA status fields is a black art.
It is all too easy to write an NMEA parser that works well on one
variant but breaks on another, delivering subtly incorrect results or
even crashing your application. Because
in the job, we collect knowledge on all variants and do parsing that
is much less likely to get tripped up.
Another issue is that some of the reports your application would
like to have are not generated by all GPSes. Estimated position error
in meters is the most obvious example; climb/sink is another. When a GPS
doesn't supply these,
gpsd can fill them in using the
same sorts of computation that more capable GPSes use.
gpsd package provides two ways for C code to get
data from a GPS or AIS receiver. Both go through the libgps.a library,
which supports two sets of entry points. The low-level interface talks directly to the GPS.
The high-level interface communicates with
an instance of
gpsd, which uses its own copy of libgps.a
to talk to the device.
A third way would be to open a socket to
gpsd protocol or raw NMEA in your application.
Before 2.0, all
gpsd-aware applications had to do this
because libgps.a didn't exist. Now that it does, the exercise is
rather pointless. Using libgps.a will probably simplify your code a
You will almost always want to use the high-level interface and go through the daemon; among other things, this means more than one application will be able to query the GPS without causing confusion. The only exception will be in very space-constrained single-user scenarios, perhaps on embedded systems or PDAs. On those it may be appropriate to use the low-level interface directly, probably with a build from source that conditions out all but one of the drivers.
For Python programmers, there is a gps.py module the high-level interface. It exports a class that encapsulates a GPS session.
A GNSS receiver takes some measurements. Later the receiver takes some time to calculate the postion fix. Later the receiver sends the results of the calculations (in unknown order) out a slow serial connection. There is no way to know what the receiver will send, or when it is done. Data just appears to *gpsd*. The *gpsd* has to accept this data, validate it, process it, and pass it on to its clients as JSON message.
The *gpsd* daemon could wait to get all the data for an epoch (measurement period) before outputing the JSON messages, but that would requite waiting for the next epoch data to appear, which would add a lot of latency. So, instead, gpsd passes in data it receives almost as soon as it receives it. Since many protocols (like NMEA) repeat the same data in many ways this leads to repeated data sent to the gpsd clients. Other protocols, like *ubx*, keep sending additional tidbits of data during the epoch, so *gpsd* has to repeat the previous data, with the new data, for a complete message.
Most receivers do not provide this data. A few, like some *u-blox* models, can provide this data. See the *gpssubframe* program, and its manual page, for further information. Beware, there be dragons.
gpsdwhenever I power-cycle my Bluetooth device?
The Bluetooth stack returns 0 for a read from a missing device, rather than -1, and doesn't set errno. This is wrong and needs to be fixed at OS level.
This is not a GPSD problem, but a result of the way Linux handles USB serial devices. In a default Linux configuration, USB serial device name do not depend on which physical port you plug the USB/serial adaptor, but on what order you plug devices in: 1st device gets /dev/ttyUSB0, 2nd gets /dev/ttyUSB1, etc....
This collides with what happens during a suspend/resume. If you
gpsd has a device active, it will hold the
device open while your laptop is asleep - but, meanwhile, the suspend
logic is shutting down hotpluggable devices to be recreated at
resume time. On resume, Linux will see that the old device is open
and recreate one with a different name, leaving
looking at a bad file descriptor.
There is a solution to this problem: create a stable gps-usb device
that is actually a symlink which gets modified by hotplug events, and
gpsd that device when you invoke it. You'll need these replacement udev rules,
and the experience required to patch them so the vendor ID in the last
one matches your GPS hardware (look in your lsusb output).