Start with four questions: who owns each part, how the SDK starts, how work reaches hardware, and what gets cleaned up on disconnection. This chapter maps the integration; use feature guides and the API reference for parameters. See versions and migration for the interface baseline.
The APP, SDK, backend and your hardware
| Part | Responsibility | Your integration |
|---|---|---|
| Console and backend | Device/model registration, license issuance, cloud binding and feature configuration | Confirm environment, device identity and model; an authorized administrator prepares prerequisites |
| Android / iOS APP | Sign-in, device connection, navigation, permissions and system audio/capture entry points | Test with the matching APP; the user grants system permissions |
| Terminal SDK | Authorization/session checks, protocol handling, events and integrated channels | Link matching headers and archives; configure public ports |
| Your application and BSP | Radio/IP, storage, display, decoding, audio output, CAN/UART and actuators | Implement drivers, UI and product interlocks; report observed results |
For the nearby connection described here, controls, HUD and media travel directly between phone and terminal. The cloud is not a relay for each media frame. Joined hotspot, started SDK, authenticated owner and usable feature are four different states.
The owner is the user bound to the device. The SDK owner thread serializes SDK execution; these are different concepts. BSP means board support package, including radio, storage and display drivers.
Choose Managed or Core first
| Product requirement | Recommended interface | Scheduling owner |
|---|---|---|
| Primary Wi-Fi, controls, HUD, navigation video and exposed feature ports | Managed: moto_terminal |
SDK task and queues; your application consumes events and connects drivers |
| Add Wi-Fi audio or independent mirroring | Keep Managed; call the required pre-start set_audio / set_mirror |
The same SDK task; mirroring requires config.network and working video |
| First adding with the current App, BLE notifications, proximity unlock, basemap storage or same-owner candidate handoff | Core: moto_sdk |
Your owner task serializes the required instances and ports |
Managed wraps Core, but their handles and event structures are not interchangeable. Core can reuse moto_network for discovery, listeners and backpressure. Choose by product requirements, then follow first connection or the reference application.
Diagram 1: terminal application lifecycle
This is the Managed startup order. Check each result and stop advancing on failure. One lifecycle-owner task performs initialization and shutdown.
Step-by-step notes
- Prepare BSP and storage
Initialize storage, clock, random source and drivers. Prepare reads of the device license and pairing record.
- config_init → create
Supply actual hardware and feature ports. create checks configuration, license and storage, returning a terminal on success.
- Configure optional audio and mirroring
Call the required set_audio / set_mirror before start and check results. Leave unused features disabled.
- start
Create the SDK task. Success means the task started, not that the radio or phone connection is ready.
- Start radio/IP and consume events
The BSP starts AP / DHCP and reports link.ready and generation. One application task uses next_event and dispatches work.
- Operate and recover connections
The SDK manages connections; driver tasks display and execute. Ordinary network loss cleans up a session without destroying the entire terminal.
config.network is the recommended transport setup and excludes advanced external transport_send/transport_close. When Managed owns primary networking, do not also accept connections or call connected/receive/disconnected. The BSP reports local-IP readiness and advances generation after link loss even if reconnection uses the same IP. See Wi-Fi and Bluetooth.
Core does not create application tasks. Follow the common owner-thread rules for networking, SDK and companion instances. moto_network_poll already polls its bound primary/mirror instances; do not poll them again. Serialize independent objects such as the video reassembler as their guides require.
Diagram 2: from connection to usable features
This is the current App’s first-add flow, requiring the Core BLE companion and primary Wi-Fi connection. The Managed Wi-Fi template does not implement the complete flow. Existing valid bindings can reconnect primary business without repeating PIN confirmation or cloud binding.
Step-by-step notes
- Discover the vehicle over BLE
Sign in and enable Bluetooth; the terminal advertises the complete SDK identifier. Discovery is not authentication.
- Establish BLE TLS, then confirm PIN
Establish the secure channel and enter the instrument PIN. READY alone does not authenticate the owner; save pairing durably before confirming.
- Cloud binding, then Wi-Fi guidance
Complete cloud binding, obtain hotspot details over authenticated BLE and follow the network-joining guidance.
- Authenticate primary Wi-Fi
Establish separate primary TLS, authenticate the owner and apply valid signed configuration and capability negotiation. Joining the hotspot alone is insufficient.
- Target feature ready
Enable an operation only when hardware integration, valid authorization, client negotiation and feature-specific runtime conditions are satisfied.
For example, Wi-Fi authentication does not establish an ANCS subscription, A2DP support does not establish the selected phone audio route, and received video is not proof of LCD presentation. Check feature configuration, relevant events and actual hardware state together.
Diagram 3: executing a vehicle command
This example is an APP-originated vehicle command. Audio callbacks, notifications and navigation actions have their own result contracts; do not apply vehicle execution semantics to all of them.
Step-by-step notes
- APP → SDK validation
Check authorization, session, command parameters and expiry, then emit VEHICLE_COMMAND.
- Event consumer → vehicle driver task
Copy the full event with connection / session / request and deadline. Do not block event consumption on slow hardware.
- Driver checks and executes once
Recheck identity, freshness and vehicle interlocks before using the real CAN / UART / actuator interface.
- Driver → SDK completion queue
Call complete with the original event. OK only queues the result; on FULL retry the still-valid result, never the physical action.
- SDK → APP result and actual state
Report success, failure or unknown from driver evidence. Telemetry still comes from the real controller; never assign an old request to a new session.
Managed moto_terminal_event owns its data and can be copied into driver queues. Core moto_event contains borrowed data; copy what you need before the callback returns. SDK port callbacks must remain bounded and must not reenter the SDK. Hand off hardware waits using the port’s documented asynchronous contract. See vehicle controls and threads and ownership.
Channels have distinct responsibilities
| Channel | Carries | Cleanup boundary |
|---|---|---|
| Primary Wi-Fi, default TCP 5004 | Authentication, controls, state, navigation and HUD | Clear that session’s temporary state and old input; ordinary disconnection retains pairing |
| Independent BLE companion | First-pairing assistance, notifications, ANCS and proximity unlock | Clear its own session; losing BLE does not end Wi-Fi navigation |
| Video UDP 5001 | H.264 / MJPEG frames | STREAM_STOP clears video; valid HUD may continue |
| Map TLS 5003 | Route-area basemaps | Follow map transaction and navigation lifetime; transfer percentage is not readiness |
| Mirror control TLS 5005 | Current-stream grant, renewal and feedback | Unexpected primary loss may retain a delegated, valid lease; whole-network loss, explicit stop or revocation ends it |
| Audio TLS 5006 | Permitted playback capture as PCM | Sharing stop, authorization loss or expiry clears the stream and old buffers; listening needs separate acceptance |
Do not place all channel data into one queue. They share product identity and authorization constraints while retaining their own sessions, streams and resource ownership. See notifications, navigation, projection, maps and audio for wiring and capabilities.
Diagram 4: stopping, restarting and destroying
Step-by-step notes
- Stop new submissions and external callers
Stop external input producers, event readers and driver access to the terminal. Retain low-level close callbacks and their contexts.
- stop → await cleanup
The lifecycle task calls stop. AGAIN means the instance remains valid; retry stop on a later tick, never force-free it.
- stop returns OK
Choose start to reuse the instance or destroy after all callers exit. Never call start / stop / destroy concurrently.
- Restart or finish destruction
Restart reloads license and binding and establishes fresh sessions. After successful destroy, clear the handle and release customer driver contexts.
Ordinary stop and network loss do not erase the license or owner. Unbinding, cloud reset and local revocation are separate flows. A successful cloud response does not prove that an offline terminal cleared the previous owner. See persistence and service recovery.
For first integration, verify discovery → authentication → actual theme change → pairing retained after reboot. Then validate required hardware execution, display, sound and failure cleanup. Continue with first connection and use troubleshooting to locate the failing stage.