trail-mate/docs/engineering/tmap-dependency.md

Released TMAP dependency and navigation integration

Native navigation is integrated in the working firmware sources. See Native saved-route navigation for the current acceptance matrix, measured pipeline, UI/session tests and target/hardware evidence. The device audit below records the KML implementation before that work; it is not the current completion status of the native-route branch.

Trail Mate consumes the independent TMAP SDK as a third-party dependency. The application owns storage adapters, UI policy, GPS integration and task scheduling. SDK readers and algorithms are not maintained as a second copy under modules/core_tmap.

Locked release

• Version: 0.2.0, experimental pre-release.
• Commit: d74b084acb61653149dec1ac161df58a92278cff.
• Published source archive SHA-256: 50cda6657a184587a1901aba965b885b335d7bc332793fcbd90cbab2bcfce371.
• License/provenance: upstream AGPL-3.0-only, LICENSE, COPYRIGHT and NOTICE.

PlatformIO declares the immutable Git dependency in platformio.ini and modules/ui_map_runtime/library.json. CMake's cmake/TrailMateTmap.cmake downloads the release archive through FetchContent, verifies its hash and exposes tmap::tmap to ESP-IDF, Linux and native test consumers. Normal builds do not depend on a sibling source checkout. The documented FetchContent source override is an explicit offline-development option, not the release configuration.

Application builds disable SDK tests, examples, host producers and desktop file adapters, and enable the bounded-stack/no-exception configuration. The upstream PlatformIO manifest excludes both desktop file-adapter implementations. Device filesystem and external-memory adapters remain application code.

What the SDK upgrade provides

The reader supports Center's native map containers, including display/search sections and selected outdoor sections in the same file. DEM selection can follow display zoom while analytical queries retain the finest stored grid.

The SDK also provides bounded leg sinks, temporary leg spools, self-contained .tmroute files and on-file spatial/distance indexes. These interfaces make it possible to release search/map memory before displaying a saved route. Updating the dependency does not connect those interfaces to the device's existing KML UI.

See upstream persistent-route API and 20 km resource evidence. The SDK's 1,768 B saved-route reader measurement is not a measurement of Trail Mate's current navigation implementation or of complete firmware RAM.

Pre-native device navigation audit, 2026-10-15

The following rows describe current working-source wiring, not physical-device acceptance. The full native route-archive workflow remains an integration task.

Stage	Current implementation	Remaining work
Endpoints	Tracker navigation dialog uses a current GPS fix or searched origin and a searched destination	Preserve named endpoints and routing policy with a native saved-route collection
Calculation	ESP Arduino worker runs bounded coordinate routing in PSRAM; explicit failure/cancellation	Integrate sink output, tested long-route budgets and suitable heuristics
Persistence	Streaming KML writer creates a pending file, checks flush and renames on save under /routes/navigation	Add native archive/spool file adapters, finalize/publish/recovery and archive metadata
Selection and activation	Saved KML list, preview, active-route configuration and manual stop	Add .tmroute list/load/delete and source-identity policy
Map drawing	Existing KML overlay uses a reduced set of at most 96 points	Query the saved route by viewport and clip candidates without losing detailed geometry
GPS progress	KML scan computes route position, remaining distance and ambiguity; independent scans gate estimated arrival	Adapt matching to bounded archive windows and test loops, intersections and stale fixes
Deviation	Full KML matching supplies distance bounds and an off-route notice	Explicit deviation/recovery policy and bounded manual/automatic replanning
Guidance and finish	Remaining-distance/progress and estimated route-end notices; manual stop exists	Maneuver lookahead/cues and an explicit completed-session transition

navigation::RouteCalculation currently selects HeapDijkstra, defaults to 4,096 search states, 2,048 output legs, a 160 KiB search-storage limit and 50,000 expansions. It retains the leg array and search storage through geometry export. Those defaults are not the SDK acceptance's integer ALT configuration and do not establish support for the real 20 km London/Kunming requests. Increasing a limit alone is not sufficient evidence of useful SD latency or available board PSRAM.

The KML navigation matcher scans complete source geometry in bounded chunks; the display's reduced 96-point overlay is not the geometry used for that match. It does not use the new archive's spatial index. Existing KML following should remain available while native routes acquire their own bounded adapter path.

The runtime implementation is guarded by ARDUINO_ARCH_ESP32 and requires PSRAM. Other platforms currently receive unsupported stubs. The portable SDK's platform independence does not establish firmware navigation parity across targets.

GitNexus reported an index 193 commits behind HEAD. The required npx gitnexus analyze refresh was attempted but exited with code 1 after parser-worker timeout retries, including the GPS runtime. The CMake helper and new route-calculation symbols were absent from the available graph. This audit therefore uses direct source inspection and the native regression suite; an empty graph result is not treated as proof that an integration has no callers. This upgrade changes release pins and documentation, not application functions or navigation state machines.

Integration validation

tests/tmap uses the hash-verified published release. Its dependency contract checks that CMake and both PlatformIO pins agree and that the copied reader/search implementation is absent. Native tests cover administrative paths, released SDK interfaces/external-memory refusal, platform-link isolation, coordinate routing, Busy/cancellation and generated KML semantics.

Optional world/China inputs exercise the application map source: pixel reads, annotations, search, media sessions, Busy, corruption, capacity and ownership. Use the current Center SD delivery paths, not removed artifact locations:

cmake -S tests/tmap -B .codex-build/tmap-dependency -DCMAKE_BUILD_TYPE=Release \
  -DTRAILMATE_TMAP_WORLD_MAP=/data/sd/maps/tmap/osm/world-osm-z0-7.tmap \
  -DTRAILMATE_TMAP_CHINA_MAP=/data/sd/maps/tmap/osm/china-osm-z8-12.tmap
cmake --build .codex-build/tmap-dependency
ctest --test-dir .codex-build/tmap-dependency --output-on-failure

Large map datasets are not vendored or downloaded by the dependency helper. The 2026-10-15 upgrade configured and built against the downloaded SDK 0.2.0 release, whose archive hash was checked again independently. All 10/10 native CTest cases passed, including the current Center-produced world and China files under artifacts/sd-v2/maps/tmap/osm. The real map-source probe retained a 14,024 B Workspace, 120 B Reader and 25,368 B two-package catalog payload on the 32-bit MinGW GCC 9.2 ABI. These are host typed sizes, not whole-device peaks.

The reproducible local evidence is retained in .codex-build/tmap-dependency/integration-0.2.0.{log,xml,json}. Results of an earlier SDK's firmware build must not be presented as validation of this release; a full target build and physical navigation acceptance remain separate.

Historical target evidence

An earlier tlora_pager_sx1262 PlatformIO build on 2026-10-15 used SDK 0.1.1 and reported 97,356 B static RAM and 4,662,485 B Flash. Those linker totals belong to that source/configuration and are not the upgraded firmware's resource figures. No new target build, flash, RAM/PSRAM peak, task-stack watermark, SD latency or power measurement is implied by changing the dependency pins.