Use this page to look up arguments and return values. For your first integration, begin with First connection. The C / C++ header is include/moto_freertos/terminal.h.
Names used in examples
| Name | Meaning |
|---|---|
t / terminal |
SDK instance created by moto_terminal_create |
e / saved_event |
An event delivered to your application; copy the entire structure for asynchronous work |
connection |
This Bluetooth connection’s number; it changes on reconnect |
session |
This secure session’s number; report results using the original event’s number |
port |
Hardware callbacks you implement for the SDK |
Function tables omit the common moto_terminal_ prefix. For example, start(t) means moto_terminal_start(t). Dimensions use pixels, time uses milliseconds, and bitrate uses bit/s.
Start and stop
Start in the order config_init → create → start. Release in the order stop → destroy.
| Call | Use |
|---|---|
config_init(&c) |
Set defaults before modifying configuration |
create(&c, &t, &error) |
Validate configuration, license and storage; on failure t is NULL and error explains why |
start(t) |
Start the SDK task; enable Bluetooth input after success |
stop(t, timeout_ms) |
Request shutdown and wait; AGAIN means shutdown is still in progress |
destroy(t) |
Release after all callers stop; returns BUSY while running or stopping |
get_status(t) |
Get a copy of runtime, authentication, connection, feature and error state |
One task should own lifecycle operations. Do not call them from driver callbacks. All APIs are task APIs, not interrupt APIs. Stopping the SDK preserves licenses and pairing records.
Required configuration and drivers
moto_terminal_config_init sets the structure size and interface version. Do not manually change struct_size or abi_version.
| Field | Value |
|---|---|
hardware_revision |
Board revision, 1–64 bytes |
firmware_version |
major.minor.patch; each part 0–65535 without leading zeros |
width / height |
Screen dimensions; both 0 for a device without a display |
rotation |
0, 90, 180 or 270; default 0 |
port.user |
Driver context pointer; keep it alive until after SDK destruction |
port.load_license |
Fill the 512-byte license, 65-byte hardware-ID buffer and 65-byte public key; return 0 on success |
port.ble_send |
Copy accepted bytes, then return their count; 0 means busy, negative means failure |
port.ble_close |
Request the specified connection’s closure without waiting for it to finish |
FreeRTOS integration also requires these storage, random-generation and clock callbacks. If the target package supplies adapters, reuse them according to its instructions:
| Field | Requirement |
|---|---|
port.read_pairing |
Read the unchanged record; output length 0 if absent, nonzero return on damage or read failure |
port.write_pairing |
Write unchanged bytes; return 0 after durable storage succeeds; use with read_pairing |
port.random |
Fill the requested number of secure random bytes; return 0 on success |
port.now_ms |
Thread-safe monotonic millisecond clock, not wall-clock time |
Optional features
| Field | Default and limits |
|---|---|
phone_state |
true; phone theme and battery |
notifications |
false; enable after Android notification display is integrated |
calls |
false; enable after call-driver integration |
ancs / ancs_ready |
Disabled; enabling requires a callback reflecting actual iOS notification subscription readiness |
h264 / mjpeg |
Disabled; each uses enabled, fps and bitrate; fps 1–30, bitrate positive |
ota |
Disabled; provide the actual update driver through moto_ota_port |
wifi_ota |
false; requires ota.handle before enabling |
Large-screen navigation uses both video and HUD. Use HUD alone with video disabled only on screens too small to mirror navigation. Video dimensions must be nonzero and even, at most 1920 wide and 1080 high. Enable only codecs connected to working decoders.
Bluetooth and event reading
| Call | Result and usage |
|---|---|
advertising(t, out) |
out must hold at least 31 bytes; receives the complete advertisement |
connected(t, &connection) |
Generates a nonzero connection number; save it in the driver context |
disconnected(t, connection) |
Notify disconnection; an old number returns STATE |
receive(t, connection, bytes, size) |
1–512 bytes; OK means all copied, FULL means none accepted |
next_event(t, &e, timeout_ms) |
One consumer task; 0 means no wait, AGAIN means no event |
Keep callbacks short. Assign slow vehicle operations and display refresh to their own tasks. See Bluetooth for the complete driver flow.
Events to handle
Names below omit MOTO_EVENT_, except for the full name MOTO_TERMINAL_EVENT_ERROR.
| Event | Fields or action |
|---|---|
PAIRING_PIN |
value is a four-digit PIN; target is validity in seconds |
PAIRING_CLEARED / PAIR / UNPAIR |
Clear or update pairing UI |
READY / AUTHENTICATED |
Encrypted channel ready / owner authenticated; feature access still depends on console configuration |
PHONE_STATE |
data.phone: theme, battery and charging |
NAV_BEGIN / NAV_END |
data.object.id: navigation ID; local end may use 0 |
HUD / HUD_EXPIRED |
data.hud: turns and distances; clear expired instructions |
WIFI / WIFI_STOP |
data.wifi.purpose: 0 video, 1 updates; release network resources on stop |
STREAM_PREPARE / STREAM_START |
data.stream: stream ID, dimensions, codec, frame rate and bitrate |
STREAM_STOP |
Stop video processing and old-frame submissions |
VEHICLE_COMMAND |
message / target / value: command, object and operation value |
NOTIFICATION |
data.notification: ID, lifetime, allowed actions, APP, title and text |
NOTIFICATION_REMOVE / FAULT_ACK |
data.object.id: notification or fault ID |
CALL / CALL_ACTION |
data.call is call state; data.call_action is an operation to execute |
ACTION_RESULT |
data.action_result.status / reason; match using request |
ANCS_SHARING |
value expresses sharing intent, not iOS subscription authorization |
REPORT_DROPPED |
request identifies an undelivered fault report |
CLOSED |
Clear PIN, video and temporary session resources |
MOTO_TERMINAL_EVENT_ERROR |
data.error.stage / code; get_status provides details |
observed_ms is when the SDK handled the event. deadline_ms is the execution deadline; 0 means none. Check the deadline and connection before hardware execution to avoid acting on stale commands.
Completion and reports
For these APIs, OK means queued; FULL means not queued. Retain arguments and retry on FULL. Asynchronous failures appear in error events or status.
| Call | When to use |
|---|---|
complete(t, &e, result, reason) |
Report a vehicle command, call action or video preparation result; SUCCEEDED or FAILED, with UNKNOWN allowed only for vehicle commands; reason is a driver error code |
wifi_ready(t, &e, &ap) |
Video hotspot is ready; ap contains actual SSID, password, IP and port |
wifi_ota_ready(t, &e, &ap, psk) |
Update hotspot is ready; psk is a fresh 32-byte random key |
report_state(t, &state) |
Report complete current vehicle data |
report_fault(t, id, active, module, code, severity) |
Raise or clear a fault; id nonzero, module 1–64 bytes, severity 0–3 |
report_call(t, id, state, actions) |
Report actual call state, id nonzero; values are in Notifications & calls |
presented(t, session, stream_id, frame_id) |
Confirm a frame after the LCD displays it, using its original stream identifiers |
keyframe(t, session, stream_id) |
Request a new H.264 keyframe |
notification_action(t, &e, action) |
Use the saved notification; 0 positive, 1 negative, if permitted |
call_action(t, &e, action) |
Use the saved valid call event; 0 answer, 1 reject, 2 hang up |
Report hotspot failure with complete(..., MOTO_FAILED, reason). Report success with the appropriate ready API.
Return values
All constants below have the MOTO_ prefix.
| Value | Meaning | Next step |
|---|---|---|
OK (0) |
Call succeeded | For submissions, await actual processing |
AGAIN (1) |
Pending or no event | Wait and continue |
INVALID (-1) |
Invalid argument | Check fields and ranges |
BUSY (-2) |
Conflicting operation | Wait for the existing operation |
AUTH (-3) |
Authentication failed | Check license or pairing |
STATE (-4) |
Stale connection or invalid timing | Stop work for the old session |
UNSUPPORTED (-5) |
Feature unavailable | Check model settings and library version |
EXPIRED (-6) |
Request expired | Cancel old work |
IO (-7) |
I/O or initialization failure | Inspect the error stage |
FULL (-8) |
Queue full; nothing accepted | Retain data and retry later |
Format stages with moto_terminal_stage_name(error.stage) and codes with moto_terminal_result_name(error.code). error.detail is library-owned static text; do not free it. For symptom-based help, see Troubleshooting.
Advanced settings and memory
Keep these defaults for the first integration. Adjust them when measurements show a resource problem.
| Field | Default / range |
|---|---|
rx_slots |
16 / 1–128; up to 512 bytes per entry |
command_slots |
16 / 1–64 |
event_slots |
8 / 2–64; failing to consume events can close the session |
task_stack |
Keep the target package’s initialized value; before changing it, confirm whether units are bytes or StackType_t entries |
task_priority |
5; below configMAX_PRIORITIES |
Standard submission APIs copy arguments. Driver context pointers are not deep-copied; keep them valid. Deeper queues consume more memory. Video buffers are configured separately through moto_video_config.
Advanced API moto_terminal_post(t, session, job, payload, size) submits up to 256 bytes to the SDK task. Its callback is moto_result job(moto_sdk *sdk, const void *payload, size_t size). The callback must not block, retain sdk or destroy the SDK, and is not automatically retried. Pointer fields copy addresses only. Session 0 is for local management. For ordinary features, use the dedicated APIs above.