GPSMON(1)

💖 NAME 💖

gpsmon — real-time GPS packet monitor and control utility ✨

Like, it literally just watches your GPS packets and lets you poke at stuff. Iconic.

---

📡 SYNOPSIS 📡

gpsmon [OPTIONS} [server[:port[:device]]]

gpsmon -h

gpsmon -V

(Yes bestie, that curly brace in [OPTIONS} is exactly how it's written. We do not fix it. We respect it. 💅)

---

🌸 DESCRIPTION 🌸

Okay so here's the vibe: gpsmon is a monitor that watches packets coming from a GPS and displays them along with diagnostic information. It supports commands that can be used to tweak GPS settings in various ways — some of those are device-independent, and some vary with the GPS chipset type. And the cute part? It will behave sanely, just dumping packets, when connected to a GPS type it knows nothing about. It's not gonna have a meltdown. It's just gonna vibe. 🫶

gpsmon differs from a navigation client in that it mostly dumps raw data from the GPS, with only enough data-massaging to allow checks against expected output. It does not use gpsd to decode packets. There are many raw data types that gpsd knows about that gpsmon does not. In particular, this tool does not do any interpolation or modeling to derive climb/sink or error estimates. Nor does it discard altitude reports when the fix quality is too low. It said "raw data or nothing," and honestly? Respect.

The casual gpsd user will be better served by the cgps clients which display navigation data the same way for all GNSS receivers that gpsd supports. Such as cgps and xgps. So like, if you just want the pretty numbers, go there. gpsmon is for the girlies who want to see the packets.

Unlike gpsd, gpsmon never writes control or probe strings to the device unless you explicitly tell it to. So while it will auto-sync to binary packet types, it won't automatically recognize a device shipping an extended NMEA protocol as anything other than a plain NMEA device. Use the -t option or the t command to work around this. ✨

gpsmon is designed to run in a terminal emulator with a minimum 25x80 size. The non-GUI interface is a design choice made to accommodate users operating in constrained environments and over telnet or ssh connections. If run in a larger window, the size of the packet-log window will be increased to fit. She adapts. Main character energy. 👑

After startup (without -a or --nocurses), the top part of the screen reports the contents of several especially interesting packet types. The "PPS" field, if nonempty, is the delta between the last 1PPS top of second and the system clock at that time.

The bottom half of the screen is a scrolling hex dump of all packets the GPS is issuing. If the packet type is textual, any trailing CR/LF is omitted. Dump lines beginning ">>>" represent control packets sent to the GPS. Lines consisting of "PPS" surrounded by dashes, if present, indicate 1PPS and the start of the reporting cycle. so much lore in one little screen tbh

Unlike gpsd, gpsmon when run in direct mode does not do its own device probing. Thus, in particular, if you point it at a GPS with a native binary mode that happens to be emitting NMEA, it won't identify the actual type unless the device emits a recognizable NMEA trigger sentence. The -t, --type option may help you. 🙈

gpsmon does not require root privileges, except maybe to access the serial port in direct mode. It will run fine as root.

---

✨ OPTIONS ✨

• -?, -h, --help — Print a usage message and exit. The classic. The "help me bestie" move. 🎀
• -a, --nocurses — Enables a special debugging mode that does not use screen painting. Packets are dumped normally, any character typed suspends packet dumping and brings up a command prompt. This feature will mainly be of interest to GPSD developers. (dev girlies, this one's for you)
• -d LVL, --debug LVL — Enable packet-getter debugging output and is probably only useful to developers of the GPSD code. Consult the packet-getter source code for relevant values. Yes, consult the source. We love a scavenger hunt. 💀
• -l FILE, --logfile FILE — Set up logging to a specified file (FILE) to start immediately on device open. This may be useful is, for example, you want to capture the startup message from a device that displays firmware version information there. (that typo "useful is" is verbatim, no cap, we keep it)
• -L, --list — Lists a table showing which GPS device types this gpsmon has built-in support for, and which generic commands can be applied to which GPS types, and then exits. Note that this does not list type-specific commands associated with individual GPS types. Read the fine print bestie, it matters. ⭐
• -n, --nmea — Force gpsmon to request NMEA0183 packets instead of the raw data stream from gpsd.
• -t TYPE, --type TYPE — Set a fallback type (TYPE). Give it a string that is a distinguishing prefix of exactly one driver type name; this will be used for mode, speed, and rate switching if the driver selected by the packet type lacks those capabilities. Most useful when the packet type is NMEA but the device is known to have a binary mode, such as SiRF binary. the glow-up option ✨

---

🦋 ARGUMENTS 🦋

This program may be run in either of two modes — as a client for the gpsd daemon (and its associated control socket), or directly connected to a specified serial device. Two modes, two vibes, both valid. 💜

By default, clients collect data from the local gpsd daemon running on localhost, using the default GPSD port 2947. The optional argument to any client may override this behavior:

[server[:port[:device]]]

For further explanation, and examples, see the ARGUMENTS section in the gps(1) man page.

If instead the argument contains slashes but no colons will it be treated as a serial device for direct connection. In direct-connect mode gpsmon will hunt for a correct baud rate and lock on to it automatically. She finds her own baud rate. Independent queen. 🌈

---

💅 COMMANDS 💅

okay bestie so while gpsmon is running, you've got a whole lil arsenal of device-independent commands. same energy as a group chat — just type and go:

• i — (Direct mode only.) turns subtype probing on/off and reinitializes the driver. so here's the tea: normally gpsmon does NOT send config strings to your device (the only exception being wakeup strings it needs to get data flowing, if any). the command i1 makes it send the exact same sequence of subtype probes that gpsd would. i0 kills probing. just i on its own toggles that bit. either way, the current driver gets re-selected, and if the probe bit is on, probes start going out immediately. ✨

⚠️ heads up: enabling probing might flip your device into another mode. specifically, it'll flip a SiRF chip into binary mode like you'd just typed the "n" command. that's a limitation in the SiRF firmware and we literally cannot fix it. 💀

also this command will generally do nothing after the first time you run it, because the device type is already discovered by then. 🙈

• c — (Direct mode only.) change cycle time. put a number after it and it's read as a cycle time in seconds. most devices are locked at a fixed 1-second cycle time, so this one may fail with a message. 😭
• l — toggle packet logging. if logging is on, it turns off and the log closes. if it's off, logging to the filename that follows the l gets enabled. it's not like just grabbing raw data off the GPS device — only whole packets get logged. the logfile opens in append mode, so you can log multiple chunks of the packet stream and they'll stitch together correctly. 🧚
• n — (Direct mode only.) with an argument of 0, switch the device to NMEA mode at the current speed; with an argument of 1, change to binary (native) mode. no argument = toggle the setting. it'll throw an error if your device doesn't have such modes.

so after you switch a dual-protocol GPS to NMEA mode with this command, it retains the info about the original type and its control capabilities. that's why the device type listed before the prompt doesn't change. periodt.

• q — quit gpsmon. Control-C also works, or whatever your current interrupt character happens to be. bye bestie 🫶
• s — (Direct mode only.) change baud rate. follow it with a number read as bits per second, like "s9600". the speed number may optionally be followed by a colon and a wordlength-parity-stopbits spec in the traditional style, e.g. 8N1 (the default), 7E1, etc. some devices don't support serial modes other than their default, so yeah, this one may fail with a message too.

🚨 Note: use this command with caution. on USB and Bluetooth GPSs it's also possible for serial mode setting to fail — either because the serial adaptor chip doesn't support non-8N1 modes, or because the device firmware doesn't properly synchronize the serial adaptor chip with the UART on the GPS chipset when the speed changes. these failures can hang your device, possibly requiring a GPS power cycle or (in extreme cases) physically disconnecting the NVRAM backup battery. not a vibe. be careful. 😭

• t — (Direct mode only.) force a switch of monitoring type. follow it with a string that's unique to the name of a gpsd driver with gpsmon support; gpsmon will switch to using that driver and display code. it'll show an error message if there's no matching gpsd driver, or multiple matches, or the unique match has no display support in gpsmon.
• x — (Direct mode only.) send hex payload to the device. after the command letter you can type hex digit pairs; end with a newline. these become the payload of a control packet shipped to the device. the packet gets wrapped with headers, trailers, and a checksum appropriate for the current driver type. the first one or two bytes of the payload may be specially interpreted — see the description of the -x of gpsctl 1.
• X — (Direct mode only.) send raw hex bytes to the device. after the command letter you can type hex digit pairs; end with a newline. these get shipped straight to the device. no wrapping, no nothing. raw. 🦋
• Ctrl-S — freeze display, suspend scrolling in the debug window.
• Ctrl-Q — unfreeze display, resume normal operation.

---

🌸 NMEA support 🌸

(these remarks apply to not just generic NMEA devices but all extended NMEA devices that gpsmon presently supports, okay?)

all fields are raw data from the GPS except (a) the "Cooked PVT" window near the top of the screen, which is provided as a check, and (b) the "PPS offset" field.

there are no device-specific commands. which generic commands are available may vary by type — peek at the output of gpsmon -l to learn more. iykyk 💜

👑 SiRF support 👑

most information is raw from the GPS. underlined fields are derived by translation from ECEF coordinates or by application of leap-second and local time-zone offsets. 1PPS is the clock lag, as usual.

the following commands are supported for SiRF GPSes only:

• A — (Direct mode only.) toggle reporting of 50BPS subframe data.
• M — (Direct mode only.) set (M1) or clear (M0) static navigation. the SiRF documentation says: "Static navigation is a position filter designed to be used with motor vehicles. When the vehicle’s velocity falls below a threshold, the position and heading are frozen, and velocity is set to zero. This condition will continue until the computed velocity rises above 1.2 times the threshold or until the computed position is at least a set distance from the frozen place. The threshold velocity and set distance may vary with software versions."

non-static mode is designed for use with road navigation software, which often snaps the reported position to the nearest road within some uncertainty radius. you probably want to turn static navigation off for pedestrian use, since it's likely to report speed zero and position changing in large jumps. 💀

• P — (Direct mode only.) toggle navigation-parameter display mode. toggles between normal display and one that shows selected navigation parameters from MID 19, including the Static Navigation bit toggled by the 'M' command.

to interpret what you see, you will need a copy of the SiRF Binary Protocol Reference Manual. 📖

🦋 u-blox support 🦋

most information is raw from the GPS. underlined fields are derived by translation from ECEF coordinates. 1PPS is the clock lag as usual. there are no per-type special commands.

---

😭 BUGS AND LIMITATIONS 😭

the PPS Offset field will never be updated when running in client mode, even if you can see PPS events in the packet window. this limitation may be fixed in a future release. (we know. we're sorry. 🙈)

---

✨ RETURN VALUES ✨

• 0 — on success. slay 💅
• 1 — on failure

---

🎀 SEE ALSO 🎀

gpsd(8), cgps, (1)gpsctl(1), gps(1), *xgps(1)

---

🌈 RESOURCES 🌈

project web site: https://gpsd.io/

---

🫶 COPYING 🫶

this file is Copyright 2013 by the GPSD project SPDX-License-Identifier: BSD-2-clause

---

💖 AUTHOR 💖

Eric S. Raymond

---

okay bestie that's the whole page!! this was GPSD, Version 3.27.5, dated 2025-11-04 — go forth and monitor those packets, you absolute icon 👑✨💜