Profile: navigation¶
Offline maps and turn-by-turn navigation from your own GPS, with no network
Stage: post-1.0
Who it is for¶
An operator who needs maps and routing with no network: a field laptop, a vehicle, a hike, an EMCOMM deployment. It builds everything from regions you choose, on your machine.
At a glance¶
| Stage | post-1.0 |
| Units | 27 |
| Disk | per region: the download plus roughly 3 to 4 times it; Navit alone is small |
| Hardware | A USB GPS receiver for position (the station profile carries gpsd). Maps and routing work without one; they just do not follow you. |
| Consent | none |
| Install | hammunition install navigation |
What it installs¶
gpsd and its clients to read the GPS receiver; Navit, an offline turn-by-turn navigator with spoken directions through espeak-ng; the OpenStreetMap regions you choose, downloaded from Geofabrik and verified (osm-regions); Natural Earth's country borders (country-boundaries), which let address search find towns on a part-of-a-country map; and those regions converted into Navit's format with a Navit configuration that loads all of them and follows the GPS (osm-navit, opened by the navit-offline launcher). For trails and terrain: QMapShack, with Garmin maps built from the same regions (osm-garmin), one Routino database over all of them for routes on foot (osm-routino), Copernicus elevation tiles for the regions (dem-copernicus) and the hillshade, slope and contours drawn from them (dem-qmapshack), and for US regions the official USGS US Topo map sheets (usgs-ustopo) made into one seamless QMapShack map (ustopo-qmapshack, which also maps the Forest Service's FSTopo sheets when you have installed usfs-fstopo by name), and USGS 3DEP bare-earth elevation (dem-3dep) for when you choose it over Copernicus with --dem-source 3dep, opened by the qmapshack-offline launcher; BRouter (brouter), QMapShack's second offline router, which weighs trail difficulty and climbs, over routing files built on the machine from the same regions and elevation (brouter-segments, with the two map-creator filters in brouter-mapcreator-profiles); vector-tile maps of the same regions (osm-pmtiles, built with the archive's tilemaker and the fixed files in vector-map-kit), which hammunition reference serve draws in a browser at http://127.0.0.1:8480/map/ (D-071); and gps-tether, which serves gpsd's position to QMapShack as NMEA, and to that browser map, on this machine only, as a systemd user service from your next login. And CoMaps (comaps), a phone-style map with offline address search and car, bike and foot routing, built from source, over CoMaps' own map files for the same regions (comaps-maps), opened by the comaps-offline launcher; it reads its position from GeoClue only, which the tether feeds once hammunition hardware apply has set GeoClue up (D-069). For the water, OpenCPN (opencpn), a marine chart plotter that shows the position and the AIS ships an SDR decodes on nautical charts downloaded while online.
Disk footprint: Navit, espeak-ng, osmium-tool and gpsd from the archive (size not yet measured), the 13.3 MB country-border file once, and the browser map's kit once (about 79 MB downloaded, 45 MB installed). Per region: the download, plus Navit's converted map at about 0.9 times the download, plus about twice the download of temporary space while it converts (the map factor measured on three regions: a 6.1 GB country-sized region converted to 4.7 GB, about 0.77 times, in 75 minutes on an i7-1185G7, and two US-state-sized regions at 0.874 and 0.856 times; the scratch on the country-sized region only). A single US state's download ranges from about 20 MB (District of Columbia) to 1.3 GB (California). QMapShack's maps, measured on one US-state-sized region: the Garmin map at 0.85 times the download with up to three times it of scratch, and the Routino database over every region at 0.67 times all the downloads together with up to six times of scratch. Terrain: about 39 MB per elevation tile, tens to hundreds of tiles a region (over 90, about 3.6 GB, for the largest contiguous US states; 449, about 17.5 GB, for Alaska), and about 5.5 MB of contours per tile. BRouter: about 8.5 MB for the zip's tree, and routing files at about 0.2 times all the downloads together (Delaware: 3.3 MB from 22.1 MB), with up to three times the downloads of scratch allowed while they build (not measured) and about 650 MB of elevation scratch for one 5-degree square at a time. US Topo, for US regions: about 8 MB a sheet, twice over once warped for QMapShack. By default only the sheets within 100 km of your grid square's centre are fetched: a few hundred sheets, about 1.7 GB of download and 3.5 GB of disk on a station with ten regions, where every sheet of those regions would be 7,284 sheets, 55 GB and 111 GB (measured from the index, 2026-10-02). Whole regions on request (Delaware about 220 MB of sheets, Vermont about 1.6 GB, Virginia about 6 GB, measured from the index on 2026-09-29). 3DEP, only when chosen: about 480 MB a tile, ten times Copernicus (Delaware about 0.9 GB, Vermont about 4.4 GB), and about 8.4 MB of contours a tile with 212 MB of scratch. Vector-tile maps for the browser: about 0.91 times each download (measured on Delaware), with up to three times the download of scratch allowed while one builds (not measured). CoMaps: a source build, measured by hand at about 11 GB of build tree with full git history (the shallow submodule fetch the engine uses is smaller and not measured) and 123 MB installed with its World maps; its own maps are tens to a few hundred megabytes a US state (Vermont 61 MB) and 15.7 GB for all of the US.
Why these belong together¶
A navigator is only useful with a position and a map, and offline it needs both already on the machine. Navit without gpsd does not know where you are, and gpsd alone is a position with nothing to show it on. The same install serves daily driving and an EMCOMM deployment with the phone network down: the maps are on the laptop before anything goes wrong, and hammunition update says when newer map data is pinned.
Packages (27)¶
gpsd, gpsd-clients, gps-tether, navit, osm-regions, country-boundaries, osm-navit, qmapshack, routino, gdal-bin, mkgmap, mkgmap-splitter, osm-garmin, osm-routino, dem-copernicus, dem-3dep, dem-qmapshack, brouter, brouter-mapcreator-profiles, brouter-segments, usgs-ustopo, ustopo-qmapshack, comaps, comaps-maps, vector-map-kit, osm-pmtiles, opencpn
What it deliberately excludes¶
Maps for phones are their own profile, phone-maps (D-067), because each is built for every region and a team's phones are not every operator's. Kiwix and the rest of the offline reference are the reference profile (D-066). No tile server program is carried (martin, go-pmtiles, mbtileserver, tileserver-gl, D-071): the browser map is served by the engine's own loopback page. Raster tiles for Xastir and QMapShack's tile layers need PostGIS, osm2pgsql, renderd and a style; that stack is documented and not built. Official trail lines from the Park Service, the Forest Service and the states are not carried as a second layer, because OpenStreetMap already has nearly all of them and a duplicate draws every trail twice; US Topo shows their official names. The Forest Service's FSTopo sheets (usfs-fstopo, trail numbers over National Forest land) are left out of the profile and installed only by name: the Forest Service publishes no checksum, so until the maintainer pins every sheet a region needs, a sheet is fetched unverified, and the plan says so sheet by sheet (D-068). USGS 1 m lidar, the PDF editions of the sheets and the historical topographic maps are not carried. Viking, Marble, GPSPrune and JOSM were measured and left out: Debian's Viking renders nothing offline, Marble's offline place index has no packaged builder, and GPSPrune and JOSM use online tiles. BRouter's published routing files (brouter.de) are left out because they are regenerated weekly with no checksum; BRouter itself is carried, over files built here (D-063). GraphHopper is carried for routes on the browser map, but installed by name only (hammunition install graphhopper-graph, D-076): its graph is about 3.7 times the downloads and took 1.2 GB of memory to build on Delaware, and this profile already carries three offline routers. OSRM, Valhalla and OpenRouteService were measured and are not carried: none has an offline desktop consumer, and Valhalla has no archive package or clean binary. Navit's GTK interface (navit-gui-gtk) is left out in favour of the internal one, which suits a touch screen and a small panel. Grid-square readouts belong to the station and dashboard tools. Organic Maps is left out: it is the same program family as CoMaps, built the same way, and one of the two is enough; Flathub's builds of either are not used, because Flatpak is not a backend here.
Install it¶
Read the plan first. It changes nothing and prints every package, build, file and system change, and every consent gate you will meet:
Then do it. The engine asks for your sudo password once, near the start,
and shows the same plan again before it asks you to confirm:
A member your machine cannot take is deferred by name and the rest installs (D-039); the plan lists each under Will NOT happen, with the reason and the command that fixes it. Installation explains how to read every part of the plan.
What you configure by hand afterward¶
Choose your map regions first, with Geofabrik's region paths, for example hammunition station set --map-regions north-america/us/vermont,north-america/us/new-hampshire; without them the map units are deferred and only Navit and gpsd install. Set your grid square too (hammunition station set --grid-square <yours>): the US Topo sheets, and the 3DEP tiles if you choose them, are bounded to a 100 km radius around it by default; without one usgs-ustopo is deferred by name and says how to fix it. --topo-radius-km N, --topo-regions a,b and --topo-all change the bound, and an install that would fetch every sheet (--topo-all) or more than 10 GB of them prints the count and size and asks you to type yes, which --yes does not answer. Optionally hammunition station set --map-freshness yearly|monthly|latest (yearly is the default and, for the 50 US states and DC, is checked against a sha256 Hammunition measured; other regions and modes are checked against Geofabrik's MD5, and the plan says which for every region). A GPS receiver must be attached and seen by gpsd; xgps, from gpsd-clients, shows whether it has a fix. For QMapShack: start it from the qmapshack-offline launcher, which writes the map, elevation and Routino directories into QMapShack's configuration; its Routino router is then expected to offer the hammunition database, used with the foot profile; for your position, gps-tether runs as a user service from your next login (start it now with systemctl --user start hammunition-gps-tether.service), making NMEA from gpsd's position and serving it on 127.0.0.1 port 10110, the host and port QMapShack's GPS Tether dialog is expected to take. For BRouter, choose it in QMapShack's Routing dock (Routino stays the default); the launcher has already pointed it at Hammunition's BRouter on 127.0.0.1, and QMapShack's own BRouter setup wizard, which downloads from brouter.de, is not needed. QMapShack's first run on the field laptop (2026-09-29) found the settings group wrong and the first tether silent, and both are rewritten (D-061's amendment); the new versions have not yet been run on a desktop, and bench session 12 (docs/reference/bench-verification-5430.md) is that check. For CoMaps: start it from the comaps-offline launcher, which records the licence answer CoMaps asks for and links your maps where it looks; for "you are here", run hammunition hardware apply once (it tells GeoClue, the only position source CoMaps reads, to take the tether's NMEA from a socket), log out and back in so GeoClue's demo agent is running, and keep gps-tether running while CoMaps is open. That route was measured with Debian's GeoClue in a private namespace, not yet on a desktop. For OpenCPN: download charts with its chart downloader while online, and add a network connection for the position (gpsd, or gps-tether on 127.0.0.1 port 10110) and one for AIS from rtl-ais or ais-catcher; none of these has been set up and tried by this project (2026-09-30). Optional layers, each its own command and none of them installed by this profile: repeaters on the maps from your own export or an open list (hammunition maps repeaters import, D-064 and D-074), infrastructure and EMCOMM points such as airfields, hospitals and the grid (hammunition maps infra import, D-075), and routes in the browser map (hammunition install graphhopper-graph, D-076); docs/guides/offline-navigation.md sections 13, 18 and 16. None of them has been drawn on a desktop yet. The tray's Services group can start and stop gps-tether once it is installed (docs/guides/tray-controls.md).
Your first ten minutes¶
- Install
stationfirst so gpsd and the GPS tooling are present. See the station profile. - Find a region path with
hammunition maps regions vermont(a case-insensitive filter; it asks Geofabrik, so it needs the network), then choose yours:hammunition station set --map-regions <region-path>[,<region-path>]andhammunition station set --grid-square FN31pr(your own locator). The sheets and terrain are bounded to 100 km around the grid square by default. - Read the plan:
hammunition install navigation --dry-run. It prints the size of every download before it asks. Read those numbers; a region and its derived maps are several times the download. - Install:
hammunition install navigation. It holds yoursudoticket open for the length of the run (see the install guide), because conversions can take hours. - Start the GPS bridge the maps read:
hammunition maps gps-tether, and checkhammunition doctorfor thegeoclueline. - Open
navit-offlinefor turn-by-turn directions, or runhammunition maps qmapshackto set up QMapShack for trails, terrain and routing on foot. - Read Offline navigation next. It says what was measured on the field laptop and what is still owed to the bench.
Take it off again¶
This removes what Hammunition itself installed and nothing else. It does not remove dependencies apt pulled in, group memberships or configuration files it wrote; the plan says so and the transaction log records them (D-004).