Skip to content

qmapshack

Offline topographic maps, trails, GPX tracks, elevation profiles and routing on foot

What it does

A map program for planning and recording trips on foot, by bike or on the water: it shows the Garmin maps osm-garmin builds from your regions, draws hillshade and slope from the elevation dem-qmapshack prepares, lays contour lines over them, plans a route on trails with the Routino database osm-routino builds or with BRouter over the routing files brouter-segments builds (trail difficulty and climbs weighed), records and edits GPX tracks and waypoints, and shows an elevation profile for any track. Its maps, terrain and routing are on the disk, so none of those needs a network.

Why you would want it

A road navigator does not know trails and has no terrain. For a hike, a search, a field day on a ridge or an EMCOMM deployment away from roads, this is the offline alternative to phone apps and web maps that stop working with the phone network. It keeps tracks in files you own.

Before it will work

Your map regions set in station config, and the navigation profile's map units installed, so there are maps, elevation and a routing database to show; start it from the qmapshack-offline launcher, which writes their directories into QMapShack's own configuration first (mapPath and demPaths under [Canvas], routino\paths under [Route]) and, when brouter and its routing files are installed, points QMapShack's local BRouter at them on 127.0.0.1 (the brouter\* keys under [Route]); choose BRouter in the Routing dock to use it. For your position, gpsd with a receiver that has a fix, and the gps-tether launcher running, which makes NMEA from gpsd's position and serves it on 127.0.0.1 port 10110 for QMapShack's Realtime source "GPS TCP/IP" to take. A gpsd on another machine (a Pi, a phone, a shack computer) is read with hammunition maps gps-tether --gpsd HOST[:PORT], and --port N serves another port; the offline navigation guide's section 12 has each setup.

How it installs

  • apt: qmapshack

Known problems

QMapShack has no offline address search: its search asks online services, and Routino routes between points, not addresses. Find the address in Navit, then plan the walk here. Routino's foot profile does not read sac_scale, so an alpine path is routed like a footpath; judge the route yourself. It stops at startup with "The specified translations XML file did not exist" if /usr/share/routino/translations.xml is missing, which apt normally prevents; hammunition doctor names it. It has no gpsd client; gps-tether stands in for one. The tether is now its own project, hammunition-gps-tether, installed by the gps-tether unit and run as a user service; the gps-tether launcher still runs hammunition maps gps-tether, which runs that installed program (found on the PATH or in ~/.local/bin, which a menu entry's PATH lacks) and refuses, naming hammunition install gps-tether, where it is not installed. The service and this launcher cannot share port 10110: with the service enabled the launcher's tether says it cannot listen and stops, and the service's feed is already the one QMapShack wants. It reads gpsd's JSON, as xgps and Navit do, writes RMC and GGA itself, bound to 127.0.0.1 in its own code, and says when gpsd has no fix. On the field laptop on 2026-09-29 it gave QMapShack's GPS source a position from a real receiver. Any number of programs may connect at once, each sent every sentence, so nc 127.0.0.1 10110 shows the feed while QMapShack is open; a program that stops reading is dropped alone. It listens on 127.0.0.1 only whatever its options say, because the feed is your position without a password; another machine reaches it through ssh -L 10110:127.0.0.1:10110. A gpsd on another machine read through --gpsd has been measured only as this machine's own gpsd, by address; phone apps, Bluetooth receivers and a rig's built-in GPS are documented and not yet tested. A rig that sends GPS on its CAT port gives that port to gpsd, and rig control then cannot use it: pick a second port, a second cable, or a separate receiver. The first version relayed gpspipe -r through socat and sent nothing, at a time when gpsd itself had stopped reporting (restarting gpsd brought a fix back within a second), so why is not established. The launcher edits QMapShack's own settings file (~/.config/QLandkarte/QMapShack.conf) only to add Hammunition's directories when they are absent, and to select the first routing database when none is selected; it refuses to touch a file it cannot read, and QMapShack's own setup dialogs change the rest. An earlier launcher wrote mapPath and demPaths under [General], where QMapShack does not read them (measured on the bench, 2026-09-29); it now moves its own directories from there to [Canvas], and QMapShack then lists the maps, the contour map and the elevation, and draws hillshade. With [Route] routino\database=-1 in the settings, QMapShack 1.17.1 loads the hammunition Routino database and selects nothing in the Routing dock's Database list, and routing does nothing without a message; it writes the -1 back on exit. The launcher now sets it to 0 when absent or negative. If the list is blank, pick hammunition in it once. The Database dock ("Needs setup...") is QMapShack's own store for tracks and waypoints, not the routing database. The launchers run hammunition, which must be on your PATH. Not yet confirmed on hardware: a route on foot, within a region or across a boundary between two.

Keeping it current

  • probe: apt policy
  • strategy: apt_upgrade

Where to get help with the software itself

The project's wiki (https://github.com/Maproom/qmapshack/wiki) and its GitHub issues.

Source: catalog/packages/qmapshack.yaml