Offline maps

The phone downloads road data in advance and sends a small area around the route to the instrument during navigation. The instrument draws roads, the planned route and a position arrow. The map canvas contains no imagery, place labels or POIs; HUD text can still show road names and turns separately.

This chapter uses Core moto_config / moto_sdk * with matching SDK package revision 27 / FreeRTOS ABI 8 headers, archives and vector-enabled reference application code. Managed exposes route/position events but no map storage port. Confirm the delivery combination in versions and migration.

The road cache is for display. Destination search, routing, rerouting and location remain the phone navigation service’s responsibility; this feature does not provide offline search or routing.

Distinguish the three kinds of data

Video still uses UDP 5001. When video stops while navigation and position remain valid, the instrument can draw its local road window. Freeze the last actual position and indicate a pause when location expires.

Prerequisites and board wiring

Complete first adding and primary connection and navigation. The board needs networking, staging memory, bounded decompression and line rendering. The map path does not need a JPEG decoder.

Use the root public P4 project matched to r25. In this fragment, terminal_map_* belongs to the reference application’s main/route_map_store.h; port these board adapter functions to your hardware:

#include "route_map_store.h"

cfg.map = terminal_map_port();
cfg.route_navigation = cfg.map.max_bytes != 0;

1. On the SDK owner thread, forward primary-instance map events to terminal_map_event(event) and call terminal_map_poll(sdk) periodically. BLE companion disconnection must not clear primary-session maps.
2. Call terminal_map_draw on the display task. fresh means the position is valid; complete means all required viewport road blocks are available. A committed snapshot alone does not establish full viewport coverage.
3. For a custom port, implement staging, sequential writes, reset and commit_vector in moto_map_port. Callbacks must not reenter the SDK. Move expensive validation to a bounded worker and return MOTO_AGAIN until a later SDK poll obtains the result.
4. Before atomically publishing, validate decompressed length, raw SHA-256, navigation/route/map identities and geometry bounds. moto_vector_read returns a read-only view borrowing the original bytes; retain them unchanged until every display reader exits.

The reference route_vector_store manages validation, cancellation and snapshot lifetime; route_vector_view draws lines. Preserve these responsibilities when connecting your memory and display drivers.

Capability negotiation and commit acknowledgement

After authentication, the phone reads PROFILE key 38 for vector version, wire/raw byte budgets, geometry limits and compression support. A complete map port with commit_vector is required to advertise vectors. Video support cannot substitute for this negotiation.

The current APP sends RVP1/RVZ1 without an image-map fallback when vector support is absent. RVS1 is a phone-side archive, not a TCP 5003 payload. MTP1/MZP1 retain their legacy image meanings. Older firmware needs the vector port before receiving road windows from the current APP.

For a window update on the same route, increment only mapRevision. Retrying a revision requires identical bytes and hashes. When route, navigation or authenticated connection changes, cancel old work, negotiate again and discard late results.

Network, storage and memory budgets

Maps use TCP 5003 on the authenticated device host; the reference hotspot is 192.168.4.1. Temporary TLS credentials come from the encrypted primary session. Reconfirm host and session after the phone changes networks.

Values below use 1 KB = 1024 bytes. Budget phone files separately from instrument memory:

All limits apply together. The 1024 KB ceiling is not the total RAM needed for maps. The reference instrument holds windows in temporary memory and clears them at navigation end; downloaded phone region files remain stored.

Keep the still-valid previous window if replacement fails. A map-only TCP failure does not clear the primary session or committed map; primary disconnection, navigation end or revocation clears that session’s maps and positions. Never extrapolate stale positions or interpret missing blocks as confirmed empty roads.

Use with the APP

1. While the phone has internet access, search and download a published region under Me → Offline maps. The catalog lists prepared archives; it does not mean every city is available.
2. Finish download and validation before joining device Wi-Fi and starting navigation. A phone background work queue extracts road windows without map screenshots.
3. Wait for device commit acknowledgement. “Device map ready” refers to the current window, not every road around the full route.
4. Replenish windows as the position changes; download additional regions when leaving local coverage. Valid route, position and HUD can still display without a road window.

Location, window updates and Wi-Fi after locking depend on phone OS execution rules. Validate the actual Android/iOS phone and firmware combination. Download completion, transfer success and visible lock-screen navigation are separate checks.

Troubleshooting

Map sources

Road data comes from OpenStreetMap / Protomaps. Preserve source information in the APP’s attribution view and archive metadata, following the delivered data’s license. Removing map text layers does not remove attribution requirements. Verify open-data road coverage separately from phone navigation search and routing coverage.