Navigation receives HUD turns, roads and distances over the primary Wi-Fi session for your instrument UI to draw. This chapter uses the managed FreeRTOS interface. Complete first adding and primary connection and enable the required model capabilities first.
Match the screen’s capabilities
| Instrument | Integration | Hardware required |
|---|---|---|
| Large screen capable of showing full navigation | Navigation video + HUD | Wi-Fi hotspot, video decoder and display |
| Small screen unable to show navigation video | HUD only: turns, roads and distances | Wi-Fi and display |
Video carries the phone’s map view over Wi-Fi. HUD carries turn and distance data over the Wi-Fi business session for your instrument UI to draw; it does not contain a base map. Integrate both paths on large screens and choose the layout in your UI. Continue handling HUD events while video is active.
Display turns and distances
Handle these events on both large and small screens. On large screens, run video decoding in a separate task so HUD updates are not blocked:
| Event | Display action |
|---|---|
MOTO_EVENT_NAV_BEGIN |
Open the navigation view |
MOTO_EVENT_HUD |
Update turns, distances and roads from e.data.hud |
MOTO_EVENT_HUD_EXPIRED |
Hide expired turn instructions |
MOTO_EVENT_NAV_END / MOTO_EVENT_CLOSED |
Exit navigation and remove old instructions |
In e.data.hud, action is the turn action; distance_m is metres to the next turn; remaining_m and remaining_s are remaining metres and seconds; road and next_road are the current and next road names.
Optional terminal navigation controls
After integrating real buttons or touch input, explicitly enable navigation.control (bit14) for the model in the console; an SDK upgrade does not automatically enable existing models. PROFILE key35 describes protocol-supported actions; the current NAV_BEGIN declares which actions this navigation permits. Show only permitted controls; model authorization alone is insufficient. Mirroring and BLE companion channels do not accept navigation actions.
| Local action | action |
|---|---|
| Zoom in one level | MOTO_NAV_ZOOM_IN (0) |
| Zoom out one level | MOTO_NAV_ZOOM_OUT (1) |
| Recenter and follow current position | MOTO_NAV_RECENTER (2) |
| Show route overview | MOTO_NAV_OVERVIEW (3) |
| End navigation | MOTO_NAV_STOP (4) |
Managed saves the complete MOTO_EVENT_NAV_BEGIN event: data.object.id is the navigation ID, session identifies its session, target=0 means navigation, and value is the allowed-action mask (test 1u << action). The input task calls moto_terminal_navigation_action(terminal, &saved_event, action) using that saved event, never substituting a newer session. Hardware adapters own debounce, long-press frequency and stale-input removal; do not forward raw touch coordinates.
MOTO_OK means queued only. A pending action for the same navigation returns MOTO_BUSY; a full queue returns MOTO_FULL. Do not automatically repeat accepted actions or buffer inputs indefinitely. Receive data.navigation_result.{status,reason,navigation,action} through MOTO_EVENT_ACTION_RESULT with message=MOTO_NAV_RESULT, matching the original request/session/navigation. APP acceptance does not establish presentation; confirm the resulting navigation state and display.
Timeout or session cancellation produces UNKNOWN, which is not proof of execution failure and must not trigger replay. Clear controls and old inputs on NAV_END, CLOSED or UNPAIR. A STOP result may arrive after NAV_END; it must not change the next navigation.
Core copies navigation ID, session, source and allowed actions inside NAV_BEGIN callbacks, then calls moto_navigation_actions(sdk, id) / moto_navigation_action(sdk, id, action) outside callbacks on the same owner thread. Do not retain borrowed callback data or reenter the SDK. Validate all five actions, consistent phone/terminal views and stale-input rejection after disconnection on both Android and iOS.
Navigation audio
HUD and video APIs do not carry navigation audio. Built-in navigation uses system / A2DP routing. AMap’s public text callback provides no original PCM, and the APP neither embeds TTS nor generates replacement speech. Wi-Fi carries only user-authorized playback that the system permits capturing; see audio integration.
Expiry and end
STREAM_STOP ends video only; keep valid HUD data. Clear expired prompts on HUD_EXPIRED and exit navigation on NAV_END or CLOSED. Business heartbeats must not extend old guidance.
Continue with video projection for large screens and offline maps for cached basemaps.