Android Error Codes and FAQ
SDK Version: 1.0.0
Platform: Android
The SDK returns enum names, exceptions, or reason strings. This document does not define unpublished numeric error codes.
Auth reason
| reason | Meaning | Recommended action |
|---|---|---|
ok | Authentication and DID retrieval succeeded | Continue to Init |
not_connected | Waiting for BLE connection failed | Check state and reconnect |
ble_not_ready | GATT/AT path is not ready | Wait; reconnect after timeout |
at_path_unavailable | Neither plain nor XOR probe produced valid evidence | Check the device, firmware, and link |
challenge_command_failed | Challenge command failed | Remove concurrent AT work and retry auth |
challenge_verify_failed | Challenge signature verification failed | Do not continue; reconnect and retry |
did_read_failed | No valid DID from AT+EFUSESN?/AT+SN? | Check firmware and device identity data |
Init reason
| reason | Meaning | Recommended action |
|---|---|---|
ok | Configuration was applied | Continue |
no_vendor_config | This host needs no vendor configuration | Continue normally |
missing_did | No authenticated DID | Return to Auth |
command_no_ok | AT response contained no OK | Preserve a response summary and retry if connected |
command_failed | AT transport threw or failed to send | Reconnect, then run Auth → Init |
FAQ
No device appears during scanning
Confirm that Bluetooth is enabled, runtime permissions are granted, the device is advertising, and XTALK_SCAN_UUID_5632G is used. Android 11 and earlier also require location permission and the system location switch.
CONNECT_OK is returned but sending still fails
CONNECT_OK is not business readiness. Wait for GATT readiness, complete Auth and Init, then check XTalkBleClient.isReadyForSend().
An AT command times out
Do not call it on the main thread and do not overlap it with Auth, Init, OTA, or other AT work. Confirm that awaitBleReady() succeeded. Send the exception type and response summary to support.
Authentication intermittently fails after reconnect
Cancel old business tasks and listeners, disconnect, wait for DISCONNECTED, and reconnect. After a device restart or OTA, use forceReauth = true.
The Release app installs but crashes at startup
Verify every AAR/dependency in the delivery manifest and ensure customer R8 rules do not remove SDK types. Provide the complete stack trace, not only an “initialization failed” description.
How should resources be released?
Stop scanning, cancel business coroutines, remove every listener, and call disconnect(). Do not register duplicate listeners from multiple screens without removing them.