GPSCTL(1)

🎀 NAME 🎀

gpsctl — control the modes of a GNSS receiver

---

✨ SYNOPSIS ✨

gpsctl [OPTIONS] [serial-port]

gpsctl -h

gpsctl -V

---

💖 DESCRIPTION 💖

okay bestie, so gpsctl is the little tool that can flip a dual-mode GNSS receiver back and forth between NMEA mode and vendor-binary mode. it can also set the baud rate on your device. but heads up: not every device has these capabilities, so don't come for me if yours is built different. 🙈

If you've got exactly one GNSS receiver hooked up to your machine and gpsd is running, you literally don't need to name the device — gpsctl does all its work through gpsd, and gpsd will go find it for you. main character energy fr. 👑

When gpsd is running, gpsctl can be run as any user, or as root. no gatekeeping.

When gpsd is not running, the device specification is required, and you'll need to be running as root or be a member of the device's owning group to have write access to the device. On many Unix variants that owning group is named dialout. iykyk.

Running under sudo will cause some loss of functionality. 😭

---

💅 OPTIONS 💅

The program accepts the following options:

• -?, -h, --help — Display program usage and exit. classic.
• -b, --binary — Put the GNSS receiver into native (binary) mode.
• -c RATE, --rate RATE — Change the receiver's cycle time. Units are seconds. Note, most receivers have a fixed cycle time of 1 second — so like, don't get your hopes up.
• -D LVL, --debug LVL — Set level of debug messages.
• -e, --echo — Generate the packet from any other arguments specified and ship it to standard output instead of the device. This switch can be used with the -t option without specifying a device. Note: the packet data for a binary prototype will be raw, not ASCII-ized in any way.
• -f, --force — Force low-level, direct, access (not through the daemon).
• -l, --list — List a table showing which option switches can be applied to which device types, and exit. cute little lookup table, love that for you.
• -n, --nmea — Put the GNSS receiver into NMEA mode.
• -r, --reset — Reset the GNSS receiver. Device port and type must be specified.
• -R, --rmshm — Remove the GPSD shared-memory segment used for SHM export. This option will normally only be of interest to GPSD developers.
• -s SPEED, --speed SPEED — Set the baud rate at which the receiver emits packets.

Use the -s option with caution. On USB and Bluetooth GPSes it is also possible for serial mode setting to fail either because the serial adaptor chip does not support non-8N1 modes or because the device firmware does not 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. 💀

• -t TYPE, --type TYPE — Force the device type.
• -T TIMEOUT, --timeout TIMEOUT — Change the sampling timeout. Defaults to 8 seconds, which should always be sufficient to get an identifying packet from a device emitting at the normal rate of 1 per second.
• -V, --version — Display program version and exit.
• -x STR, --ship STR — Send the specified control string to the GNSS receiver. C-style backslash escapes in the string are decoded. Use \xNN for hex, \e will be replaced with ESC.
  • In normal mode, through gpsd, the decoded string is passed through, unchanged to gpsd which in turns sends it to the receiver. Headers, checksums, and suffixes must be provided. (you're on your own for the packaging, bestie 🫶)
  • In low-level, (direct) mode gpsctl will provide packet headers and trailers and checksum as appropriate for binary packet types, and whatever checksum and trailer is required for text packet types.
  • You must include the leading $ for NMEA packets.
  • When sending to a UBX, Allystar or CASIC device, the first two bytes of the string supplied will become the message class and type, and the remainder the payload.
  • When sending to a Navcom NCT or Trimble TSIP device, the first byte is interpreted as the command ID and the rest as payload.
  • When sending to a Zodiac device, the first two bytes are used as a message ID of type little-endian short, and the remainder as payload in byte pairs interpreted as little-endian short.
  • For all other supported binary GPSes (notably including SiRF) the string is taken as the entire message payload and wrapped with appropriate header, trailer and checksum bytes.

The argument of the forcing option, -t, should be a string which is contained in exactly one of the known driver names; for a list, do gpsctl -l. ✨

Forcing the device type behaves somewhat differently depending on whether this tool is going through the daemon or not. In high-level mode, if the device that daemon selects for you doesn't match the driver you specified, gpsctl exits with a warning. (This may be useful in scripts. script girlies rise up 📜)

In low-level mode, if the device identifies as a Generic NMEA, use the selected driver instead. This will be useful if you have a GPS device of known type that is in NMEA mode and not responding to probes. (This option was originally implemented for talking to SiRFStar I chips, which don't respond to the normal SiRF ID probe.) the lore is real.

If no options are given, the program will display a message identifying the GPS type of the selected device and exit. vibe check complete.

Reset (-r) operations must stand alone; others can be combined. gpsctl will execute multiple options in this order: mode change (-b or -n) first, speed changes (-s) second, cycle rate (-c) third and control strings (-x) last. it's giving very organized. 💅

---

🌈 ENVIRONMENT VARIABLES 🌈

By setting the environment variable GPSD_SHM_KEY, you can control the key value used to designate the shared-memory segment removed with the -R option. This will be useful mainly when isolating test instances of gpsd from production ones.

---

🌸 EXAMPLES 🌸

• gpsctl /dev/ttyUSB0 Attempt to identify the device on USB serial device 0. Time out after the default number of seconds. Adding the -f will force low-level access and suppress the normal complaint when this tool can't find a GPSD to work through.
• gpsctl -f -n -s 9600 /dev/ttyUSB0 Use low-level operations (not going through a gpsd instance) to switch a GPS to NMEA mode at 9600bps. The tool will identify the GPS type itself.
• gpsctl -x '\xb5\x62\x0a\x04\x00\x00\x0e\x34' Send a request for UBX-MON-VER to a gpsd connected GNSS receiver.

---

💀 BUGS 💀

• SiRF GPSes can only be identified by the success of an attempt to flip them into SiRF binary mode. Thus, the process of probing one of these running in NMEA will change its behavior. not it being sneaky like that. 🙈
• Baud rate and mode changes work in direct mode but are not reliable in client mode. This will be fixed in a future release. (manifesting 🕯️)

---

⭐ RETURN VALUES ⭐

• 0 — on success. ate. 🎀
• 1 — on failure.

---

🦋 SEE ALSO 🦋

gpsd(8), gpsdctl(1), gps(1), ubxtool(1), zerk(1)

---

🧚 RESOURCES 🧚

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

---

👑 COPYING 👑

This file is Copyright by the GPSD project

SPDX-License-Identifier: BSD-2-clause

---

💜 AUTHOR 💜

Eric S. Raymond

---

and that's the whole page, bestie — no cap. this one's from GPSD, Version 3.27.5, dated 2025-11-04. go forth and configure your receiver, you absolute icon. 💖✨🎀