6.5 Persistent Routes and Viewport Reads

Persistent Routes and Viewport Reads

TMAP supports a route lifecycle intended for constrained devices: plan with an explicit search budget, write the result to storage in bounded steps, release search memory, and read only the route pages needed by a view or distance window. The saved route is independent of the map container and conventionally uses the .tmroute extension.

This is SDK functionality. Center supplies the real map inputs used for the tests. Trail Mate firmware is unchanged, and copying a route file does not add a new route-loading UI to the device.

What the SDK implements

• Coordinate/prepared integer routes can write clipped legs to an idempotent file spool instead of requiring a complete result array.
• Search parent chains are emitted in bounded steps. Temporary candidates can be overwritten; only a successful summary publishes the final count and cost.
• A streaming exporter converts one leg at a time into checked 1 KiB pages, preserving route order, full geometry, cumulative distance and explicit gaps.
• A spatial/distance tree is built on the file, bottom-up, without retaining a route-length-sized index in memory.
• The reader opens a 192-byte header, traverses only relevant index nodes/pages, and yields candidate segments to the application's projection/clipping callback.
• Independent bounded validation checks every stored record/page/node, including data outside the current view. Cancellation, Busy and budget failures are explicit.
• Coordinates can be displayed after the source map is closed. Stored edge IDs require the original map identity/build/revision before being exposed.

The file stores geometry and graph references, travel mode and ascent-cost ratio. It does not freeze current access permissions, GPS matching state or navigation progress. Display view and along-route progress are independent windows.

Responsibility split

Responsibility	Owner
Route search, leg/geometry conversion, codec, checksums and bounded retrieval	TMAP
Map raster/POI/DEM/road-network production	Center
SD/FatFS adapter, exclusive file creation, durable sync and atomic publication	Device application
Route names/collections, deletion/recovery, task scheduling and navigation UI	Device application
GPS updates, progress, deviation and replan policy	Device application

The application creates an exclusive temporary output, finalizes it successfully, checks platform synchronization, then commits it to its collection. The library does not choose a device SD directory or perform filesystem recovery. An uncommitted, cancelled or truncated result must not be treated as a complete route.

Real 20 km acceptance

The primary inputs are the exact Center-generated maps/tmap/osm/london-osm-z13-17.tmap and maps/tmap/osm/kunming-osm-z13-16.tmap builds recorded in the SDK's raw report. Both maps are hashed against Center's delivery manifest before route tests.

Metric	London	Kunming
Actual geometry length	20.779 km	20.267 km
Clipped legs / unique points	550 / 1,171	200 / 351
Saved route file	43,776 B	14,592 B
Configured search payload	2,108,244 B	1,583,956 B
Export payload after search release	11,800 B	11,800 B
Independent saved-route read payload	1,768 B	1,768 B
Whole geometry read	34,560 B	10,496 B
Small midpoint spatial read	1,728 B	1,600 B

Search is still substantially more expensive than saved-route reading. Both 32,768-state requests fail; London's 49,152-state request also fails. These failures are part of the retained evidence. Persisting a result does not spill the search queue or labels to SD and does not make full planning fit a few-KiB MCU.

Each successful case checks every leg and complete geometry against the existing array route. Search buffers are freed before export, and the map/graph are closed before reopening the route. Normal and every-seventh-operation Busy output must have identical SHA-256.

For both 20 km routes, start/midpoint/end views are tested at z12, z14, z16 and z18 in a 320 x 240 viewport. Indexed draw counts must match a separate complete-route projection/clipping scan. At the midpoint, London reads 15,424/3,904/2,880/1,728 B at those zooms; Kunming reads 7,104/3,904/2,624/1,600 B. These are cold library-cache logical reads, with header reads separate. They are not physical SD latency.

Ownership and limits

The measured 32-bit read payload is a 1,216 B workspace, 160 B reader and 392 B query cursor. An independent external-only provider measures a 1,768 B peak, three external requests, zero internal requests and zero live bytes after reset. Refusing external allocation returns BudgetExceeded without an internal fallback. Three owner controls add 36 B and the provider control adds 24 B in this ABI.

Filesystem/driver buffers, allocator overhead, display state and task/call-chain stack remain additional costs. Provider instrumentation verifies the PSRAM-first policy through an adapter; physical board RAM/PSRAM peaks remain unmeasured.

The route-only executable's linkage is checked to exclude raster, package, graph, search, writer, geometry export and viewport conversion implementations. The archive CRC table occupies 64 constant bytes. A whole-route overview may read all pages, and intersecting pages can contain off-screen candidates; only clipped segments are drawn. Fixed storage bounds hold in either case.

The SDK host suite has 40 passing CTest entries, including route behavior, exclusive save/reopen, corruption/truncation, exact file budgets, interleaved cursors, date-line crossing, clipped endpoints under Busy, no implicit allocation, installed consumers and isolated route-reader linkage. Core-only and ESP32-S3 cross builds pass; individual-frame gates are 256 B on host and 240 B on ESP. These compiler gates do not replace hardware stack measurements.

See the SDK API and workflow, 20 km evidence and reproduction commands, raw results and wire format. Map production and capabilities are covered in 6.1 Creating a Map Pack with Center, 6.2 TMAP Maps and Terrain and 6.4 TMAP SDK and Resource Budgets.