Find the step where the problem starts, then inspect that part of the connection. The sections below follow common first-integration problems.
The APP cannot find the board
- Confirm the board and wireless chip are running, and the phone has granted Bluetooth permission.
- Check that you advertise the complete 31 bytes returned by
moto_terminal_advertising. - Check the service UUID against Bluetooth.
Discovery only verifies advertising. Once the board appears, continue with connection and pairing checks.
Bluetooth connects, but pairing fails
First check whether the instrument displays a PIN:
- No PIN: check TX notification subscription, whether
ble_sendactually transmits, and whether the application keeps callingnext_event. - PIN appears but fails: include leading zeros, check expiry, then check that pairing storage succeeds.
- Pairing is required after every restart: inspect pairing-record storage callbacks. Do not erase the record on boot.
If authenticated but a feature is missing, check the device model’s settings and get_status().enabled_capabilities.
SDK creation fails
Print the error returned by creation, keeping the stage, error name and description:
printf("%s: %s (%s)\n",
moto_terminal_stage_name(error.stage),
error.detail,
moto_terminal_result_name(error.code));
| Stage | Check first |
|---|---|
config |
config_init call, firmware version, dimensions and callbacks |
license_read |
All 512 license bytes were read |
license_verify |
License, public key and hardware ID match |
storage_read / storage_write |
Pairing record can be fully read and saved |
memory / task |
FreeRTOS heap, application task stack and SDK worker stack |
tls / core |
Library and project configuration match the delivered package |
Start with your target package’s stack defaults and adjust using measured remaining stack. Confirm whether sizes use bytes or StackType_t entries; do not copy values from another board.
Navigation starts, but the screen is black
This section covers large screens with both video and HUD. Check HUD updates and video display separately: working HUD does not prove the video path works.
Record whether each stage is reached:
Hotspot connectable → STREAM_PREPARE reported successful → STREAM_START received
→ UDP packets arrive → Decoder outputs pixels → LCD display completes
Inspect the driver where progress stops. Check codec, dimensions, RGB565 byte order and display buffers. Call presented only after the LCD displays the frame.
If only the second navigation run fails, check that the old video task stopped and that old and new session / stream_id values are not mixed.
Queues fill or connections keep dropping
MOTO_FULL means the SDK did not accept this submission. Retain and retry it later. Do not repeat data already accepted with MOTO_OK.
If this happens frequently, check whether decoding, display refresh or slow hardware operations block event consumption. Move slow work to the appropriate driver task. An event_queue error usually means the application did not read events promptly.
Test before release
| Test | Pass condition |
|---|---|
| Pair and restart | PIN works; pairing survives restart |
| Vehicle control and controller timeout | Real action agrees with APP result; failures are visible |
| Repeated navigation start and stop | Fresh frames appear; old prompts and frames stay cleared |
| Phone lock and notification permission withdrawal | Notification and call UI update correctly |
| Reconnect and explicit unpair | Old commands are not executed; the old owner loses control after unpairing |
Test with the target phones, display and controller. Record the APP, SDK, firmware and board versions.
For firmware updates, also implement Flash writes, image verification, boot switching and power-loss recovery. A completed transfer does not mean the new firmware is installed.
If you still need help, send the technical team your versions, error stage and reproduction steps. Exclude licenses, PINs, keys and hotspot passwords.