Navigation Video & HUD Integration

Large screens integrate navigation video and HUD together. Use HUD alone only when the screen is too small for navigation mirroring. These are not mutually exclusive features. First pair the FreeRTOS terminal over Bluetooth and enable the relevant features in the device model’s settings.

Match the screen’s capabilities

Instrument	Integration	Hardware required
Large screen capable of showing full navigation	Navigation video + HUD	BLE, Wi-Fi hotspot, video decoder and display
Small screen unable to show navigation video	HUD only: turns, roads and distances	BLE and display

Video carries the phone’s map view over Wi-Fi. HUD carries turn and distance data over BLE 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.

For large screens, complete both the HUD and video sections below. For small screens unable to mirror navigation, complete HUD integration and leave video disabled.

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.

Check: start navigation on the phone and confirm updates appear. End navigation or disconnect and confirm old arrows disappear.

Configure video support

After integrating HUD on a large screen, configure its supported decoder before creating the SDK. For example, a 1024×600 screen with MJPEG:

c.width = 1024;
c.height = 600;
c.mjpeg.enabled = true;
c.mjpeg.fps = 13;
c.mjpeg.bitrate = 12000000; // bit/s

These are example values. Choose a frame rate your display can sustain. Use c.h264 for H.264 support. Each enabled codec needs 1–30 FPS and a positive bitrate. Dimensions must be nonzero, even, and no larger than 1920×1080.

Prepare the hotspot and display

e is the original event. For asynchronous completion, use the copy saved when it arrived.

Event	Board action	Completion
`MOTO_EVENT_WIFI`, `purpose=0`	Start the hotspot, IP configuration, DHCP and UDP listener	`moto_terminal_wifi_ready(t, &e, &ap)`
`MOTO_EVENT_STREAM_PREPARE`	Prepare decoder and receive/display buffers for `e.data.stream`	`moto_terminal_complete(t, &e, MOTO_SUCCEEDED, 0)`
`MOTO_EVENT_STREAM_START`	Receive this stream; save `e.session` and `stream_id`	Confirm frames after actual display
`MOTO_EVENT_STREAM_STOP`	Stop receiving, decoding and display submissions	Release this stream’s resources

STREAM_STOP ends video, not navigation: do not clear valid HUD data just because video stopped. Clear expired prompts on HUD_EXPIRED and navigation UI on NAV_END or CLOSED.

Prepare the hotspot within 30 seconds and video within 10 seconds. Report failures using complete(..., MOTO_FAILED, reason). A Wi-Fi request with purpose=1 is for firmware updates, not video.

ap is a moto_terminal_hotspot. Fill its actual SSID (1–32 bytes), password (8–63 bytes), IP and UDP port. The current APP navigation stream uses 192.168.4.1:5001. Report readiness after the hotspot is connectable; keep passwords out of logs.

Turn packets into displayed frames

The reassembler in moto/video.h joins UDP packets into compressed frames. Your decoder converts those frames into pixels:

UDP → moto_video_receive → complete-frame callback
→ MJPEG / H.264 decode → LCD display completion → moto_terminal_presented

Create the reassembler with moto_video_create. After STREAM_START, configure the stream using moto_video_begin_codec.
From one video task, call moto_video_receive and call moto_video_tick every 10–20 ms. Preserve UDP packet boundaries; each packet is at most 1400 bytes.
Check the current phone’s source IP and port at the socket layer. Video UDP is unencrypted; do not expose it to the public internet.
Frame memory is valid only during the callback. Copy it into your own buffer for asynchronous decoding.
After the LCD actually displays a frame, call moto_terminal_presented(t, saved_session, stream_id, frame_id). Receiving or decoding it is not yet display completion.

Call moto_terminal_keyframe when the H.264 decoder needs a new keyframe. On stop, navigation end or disconnect, cancel the old stream and ignore its late decoder callbacks.

Check repeated navigation

Large screens: check that map video and HUD data both update and decoding does not block turn instructions. Check orientation, aspect ratio and text clarity.
Small screens unable to mirror: keep video disabled; verify turns, roads and distances, including expired-data cleanup.
Both: repeat “start navigation → end → start again.” Fresh content should appear without old prompts or frames returning. See black-screen troubleshooting.