Skip to content

gps-tether

Your GPS position on 127.0.0.1 for QMapShack, the browser map and GeoClue, as a user service

What it does

Reads your position from gpsd and serves it, on this machine only, in the two shapes programs ask for: NMEA sentences on 127.0.0.1 port 10110, the GPS TCP/IP source QMapShack and many other mapping programs offer, and a server-sent-event stream at http://127.0.0.1:10111/position that the offline browser map draws your dot from. Where hammunition hardware apply has set GeoClue up it also serves GeoClue a unix socket, which is how CoMaps gets a position (D-069). This unit installs the program and a systemd user service that starts it at login and restarts it if it stops.

Why you would want it

QMapShack and the browser map have no gpsd client of their own. The tether is the small, local bridge: one process, started once, that every map reads. As a service it is simply there — no terminal window to leave open and forget — and it is a separate project with its own releases, so a fix to it does not wait for an engine release. It is the alternative to running hammunition maps gps-tether by hand or from QMapShack's menu entry.

Before it will work

gpsd running with a receiver that has a fix (the station profile's gpsd is socket-activated; the first client wakes it). Nothing in station config. The service starts at your next login; to start it now run systemctl --user start hammunition-gps-tether.service (the install does not, and says so in the plan).

How it installs

  • prebuilt tarball from https://github.com/Renegade-Penguin/hammunition-gps-tether/archive/refs/tags/v0.1.1.tar.gz
  • The tag's source tree, installed to /usr/local/share/hammunition/gps-tether and handed to the operator. Nothing is built; nothing runs as root but the copy. The tree is the operator's, so anything running as you can change the program the service runs.

What it changes on your machine

  • installed tree — /usr/local/share/hammunition/gps-tether is created and handed to the operator who ran the install by an explicit chown step in the plan (D-043): the software keeps settings, logs or data beside its executable, so the tree has to be writable by whoever runs it. On a shared machine that means anyone who can act as that user can change what the launcher runs.
  • /usr/local/share/hammunition stays root-owned; the tree itself is replaced whole on every install, so anything the software wrote inside it is lost then
  • undo: hammunition uninstall gps-tether removes the tree

Known problems

One tether per machine. The service and a foreground run — QMapShack's "GPS position for QMapShack" menu entry, or hammunition maps gps-tether — cannot share port 10110: whichever starts second reports "cannot listen" and stops. With the service enabled you do not need the menu entry; stop the service first (systemctl --user stop hammunition-gps-tether.service) if you want a foreground run, for another gpsd with --gpsd HOST say. It listens on loopback only, but loopback is not per-user: any local account can read your position from it. The user service starts at login only when your user manager is running; on a machine you never log in to graphically it does not start until you do (or loginctl enable-linger, which hammunition does not set for this unit). The tether needs Python 3.11 or later; Ubuntu 22.04 and Pop!_OS 22.04 ship 3.10, where it will not start. The unit does not restart a tether that exited 3, its refusal (a taken port, root, a bad option); a crash, exit 1, is retried every 5 seconds. There is no hammunition-gps-tether command on your PATH: the program is the installed tree run by the service, and hammunition maps gps-tether runs the same tree in a terminal. Measured on the field laptop (bench session 13): the service started from this unit, active on both ports, and still active at login after a reboot (2026-10-03); a suspend and resume with it running is not yet measured. A change to the tether's options means editing the unit by hand or running it yourself — the engine renders the unit with no arguments and replaces it whole on a reinstall.

Keeping it current

  • probe: github release (Renegade-Penguin/hammunition-gps-tether)
  • strategy: reinstall
  • Tagged releases, no release assets yet. A tag is a new tarball URL and a new digest; re-pin both (and the tag in the comment).

Where to get help with the software itself

Issues on the hammunition-gps-tether repository for the tether itself; gpsd's own mailing list and gpsmon / cgps for a receiver that has no fix.

Source: catalog/packages/gps-tether.yaml