GPS Navigator and Multi-Area Offline Maps

This guide covers ATGM336H wiring, the OpenStreetMap Carto source, named area packages, dark maps, SD layout, controls, automatic package selection, track recording, and practical storage limits for firmware 3.8.0.

GPS wiring

Power the device off before connecting or removing the module. Every exposed signal is 3.3 V.

The header is physically left-to-right:

GPIO15  GPIO14  GPIO12  GPIO13  GPIO11  GND  3V3

Firmware uses UART1 at 9600 baud, 8-N-1. GPIO11/12/13 remain available to the SD bus. A first outdoor fix can take several minutes; NMEA reception proves the electrical connection but is not itself a position fix.

Why the builder uses a local OpenStreetMap renderer

The requested appearance is OpenStreetMap Standard, also called OpenStreetMap Carto. It includes the dense data present in the supplied reference screenshot:

• roads and road names;
• building footprints and available house/building numbers;
• named properties, businesses and facilities;
• POI symbols for shops, food, healthcare, fuel and other mapped features;
• bus stops and public-transport features;
• footways, hiking paths and trails;
• parks, forests, land use and water;
• neighborhoods and fine place labels.

Only information contributed to OpenStreetMap can appear. The builder cannot invent a missing business name, address, path or POI.

Do not point the builder at tile.openstreetmap.org. Its community tile policy prohibits bulk downloading and offline packages. The supported workflow imports an OpenStreetMap .osm.pbf extract into a local Docker renderer and downloads tiles from 127.0.0.1. The renderer uses the open-source Carto style that powers OpenStreetMap Standard.

Relevant upstream projects and policies:

• OpenStreetMap tile usage policy
• OpenStreetMap Carto
• Geofabrik Alabama extract
• Local Docker tile server

Every package records the required OpenStreetMap attribution. If map images are displayed elsewhere, keep © OpenStreetMap contributors visible.

One-time local Carto setup on Windows

The map-builder GUI now manages this setup; normal use does not require server commands.

1. Install and start Docker Desktop, then wait until its Linux engine reports ready.
2. Download the regional .osm.pbf you need. Alabama is much easier to import than the full United States.
3. Launch python tools/offline_map_builder.py and click Prepare / Start Local OSM.
4. Select the .osm.pbf file and confirm the one-time import. Every Docker/import line is printed immediately in the terminal, and the GUI shows an indeterminate activity bar until the renderer answers a real tile request.
5. Leave the local XYZ template at http://127.0.0.1:8080/tile/{z}/{x}/{y}.png and build normally. If the prepared container is stopped later, Test source and Build Area Package restart it automatically.

The imported database persists after Docker or the PC restarts. It can take a long time and substantial disk/RAM to prepare, but it is performed only once.

The command-line helper remains available for advanced/manual setup:

python tools/osm_carto_server.py import `
  --pbf "C:\Maps\alabama-latest.osm.pbf" `
  --volume doomsday-osm-alabama

Then start the local renderer:

python tools/osm_carto_server.py start --volume doomsday-osm-alabama

The tile address will be:

http://127.0.0.1:8080/tile/{z}/{x}/{y}.png

Useful lifecycle commands:

python tools/osm_carto_server.py status
python tools/osm_carto_server.py stop

Stopping the container does not delete the imported database. The helper intentionally refuses to overwrite an existing Docker volume.

Run the area-package builder

Install Python dependencies and launch the GUI:

python -m pip install -r tools/offline_map_requirements.txt
python tools/offline_map_builder.py

For the reference appearance choose:

• Source: OpenStreetMap Standard (local Carto)
• Local XYZ template: http://127.0.0.1:8080/tile/{z}/{x}/{y}.png
• Map style: Standard

Build Area Package always performs its own mandatory source preflight before it creates or changes the output folder, so Test source is optional. During preflight the progress bar moves in indeterminate mode; after the source responds it changes to exact completed-tile progress. The launching terminal records every phase, URL attempt, retry, tile conversion, file write, reused tile, progress update, cancellation, error and completion. Dark High Contrast keeps the same labels/icons but transforms the pre-rendered Carto artwork into a permanent dark, high-contrast night palette. A Standard package can also be switched to night colors on the device, so a second package is not required.

The legacy USGS Topo and Shaded Relief choices remain available through zoom 16, but they do not contain the same street-level POI density.

Build small named areas

Use Center + radius for a city center, neighborhood, park or regularly visited area. Give every package a unique short name such as:

Auburn Downtown
Chewacla Trails
Montgomery Center
Birmingham Airport

The builder converts that display name into a FAT-safe folder name. It creates one independent folder containing map.ini, tiles, a resume marker and a README. Interrupted matching builds resume CRC-valid tiles. If bounds, source, style or zoom changes, use a new package name; the builder refuses to mix incompatible tiles.

Zoom 20 is supported, but it should be used only for small areas. Each added zoom level can add roughly four times as many tiles.

Conservative uncompressed/RLE-worst-case examples near Auburn for zoom 14 through the selected maximum are:

Actual DMT2 size is shown after the build and is often lower because flat map colors compress well. The GUI’s estimate is intentionally conservative.

New packages keep the renderer’s full 256×256 tile resolution. This retains much more small text and icon detail than the old 128×128 package format. Firmware still accepts legacy 128×128 DMT1 maps.

SD-card layout

Create this structure on the FAT32 card:

/Offline-Map/
  map list/
    Auburn Downtown/
      map.ini
      package-build.ini
      README.txt
      tiles/
        <zoom>/<x>/<y>.dmt
    Chewacla Trails/
      map.ini
      package-build.ini
      README.txt
      tiles/
        <zoom>/<x>/<y>.dmt
  tracks/
    YYYYMMDD-HHMMSS.csv

Copy the complete named output folder—not its loose contents—into /Offline-Map/map list/. Add or remove as many area folders as the SD card and ESP32 package-list memory can practically hold. Package metadata is allocated in PSRAM when available rather than using a small fixed slot count.

For migration, a legacy /Offline-Map/map.ini plus /Offline-Map/tiles package is still discovered and appears in the area list.

Device behavior

Open GPS Navigator. Without a valid area package it remains a complete raw receiver dashboard showing:

• NMEA/receiver and fix status;
• satellites and HDOP;
• latitude and longitude;
• altitude and speed.

Press OK and choose Choose Area Map to browse every valid named folder. The active package is marked. Manual selection opens that package at its center.

Choose Center on GPS to:

1. read the current valid GPS coordinates;
2. search all named package bounds;
3. select the overlapping package with the highest maximum zoom and tile resolution;
4. center on the fix and enable live follow.

If no saved package covers the position, a red message popup appears and then returns to the raw GPS data page. Overlapping packages are safe; the most detailed one wins automatically.

Map controls

The double-click window is 280 ms. The brief delay on a single UP/DOWN press is necessary to distinguish pan from zoom.

The map includes a north marker, a metric scale bar, the GPS course/position marker, active recording indicator and recent in-memory track breadcrumb. Zoom is clamped to the package’s own range, up to firmware maximum 20.

GPS Options

• Track Recording: start a new CSV or stop and save.
• Center on GPS: find/switch to the best covering package and follow the fix.
• Choose Area Map: manually browse named packages.
• Night Colors: switch a Standard package between its original colors and a cache-time dark high-contrast view without using extra SD space. A package built as Dark High Contrast is permanently dark.
• GPS / Map View: move between the graphical map and raw receiver data.
• Map Details: source, style, resolution, zoom, size and bounds.
• Exit Navigator: save/stop GPS work and release UART1.

Track recording

Tracks are independent of the selected map and are always written under /Offline-Map/tracks/. Recording also works with no map package.

CSV columns:

utc_date,utc_time,latitude,longitude,altitude_m,speed_kmh,course_deg,satellites,hdop

A point is written after at least three seconds and about 2.5 m of movement, or every fifteen seconds while stationary. Data flushes periodically and when recording stops, the navigator exits, Power opens or the SD card is removed.

Troubleshooting

• Local source unavailable / WinError 10061: nothing is listening at 127.0.0.1:8080. Start Docker Desktop, wait for its Linux engine, and click Prepare / Start Local OSM. A failed mandatory preflight leaves the selected package folder untouched.
• Blank/missing local tiles: confirm the selected coordinates fall inside the .osm.pbf region imported into Docker.
• No saved area maps: check spelling and nesting of /Offline-Map/map list/<area>/map.ini.
• Map tile unavailable: recopy the complete area folder or rerun the identical build to repair CRC-invalid/missing tiles.
• No saved map covers this GPS position: create another small package whose bounds contain the shown latitude/longitude.
• NO NMEA: verify module TX → GPIO14, common ground, 3.3 V and 9600 baud.
• WAIT FIX: move outdoors with the antenna unobstructed and allow time for acquisition.
• Small label absent: verify the object is present in OpenStreetMap and that the package includes zoom 19/20 around it.
• SD removal releases map/package caches and stops recording while the raw UART receiver page remains available.

The navigator is an offline map viewer and breadcrumb recorder, not a turn-by-turn routing, traffic or address-geocoding engine.