Android SDK 1.0.0 API Reference

SDK Version: 1.0.0
Platform: Android

This is the signature index and behavior card set for customer APIs. Tables specify purpose, preconditions, defaults, results/errors, thread, cleanup, and an example link. Diagnostic facilities are not customer APIs.

Common rules

• timeoutMs values are non-negative milliseconds. Run GATT/AT/RF/device-waiting operations off the main thread.
• A Boolean means only the success defined by that call; asynchronous completion may still arrive through callbacks.
• null means no valid value, failure, timeout, or unsupported operation unless stated otherwise.
• AT, Auth, Init, file operations, and mode changes share the radio and must not overlap.
• Remove every listener with the same instance passed to its add method.

XTalkBleClient: initialization, state, and connection

Full signature	Purpose/precondition	Return/error/thread/lifecycle	Example
setApplicationContext(context: Context?)	Retain application context before init	Unit; null clears	Setup
ensureInitialized(): InitResult	Idempotent core/callback init	Continue only for INIT_OK	Setup
addListener(listener: DeviceStateCallback) / removeListener(listener)	Scan/connection state	Main-thread fanout; same-instance pair	Scan
startScan(timeoutMs: Int = 5000, minRssiDbm: Int = -100, serviceUuids: List<String> = emptyList()): ScanStartResult	Permissions/Bluetooth/Init	Request result; devices via callback; pair stop	Scan
stopScan(): Unit	Cancel scan	Idempotent	Scan
connect(device: XTalkDevice, timeoutMs: Int = 5000, maxReconnectAttempts: Int? = null): ConnectResult	Selected device; background	Request outcome, not CONNECTED confirmation	Connect
awaitConnected(macAddress: String? = null, timeoutMs: Long = 8000): Boolean	Background	False on error/disconnect/deadline; waiter auto-removed	Workflow
ensureGattServicesOpened(forceReset: Boolean = false): Unit	CONNECTED; background	Reopen GATT services; reset bindings when true	Lifecycle
awaitBleReady(timeoutMs: Long = 8000): Boolean	CONNECTED; background	Stable GATT/AT readiness	Connect
disconnect(sendRemoteCommand: Boolean = true): DisconnectResult	End session; background	Clears cache/ready/AT; use false for broken link	Cleanup
awaitDisconnected(timeoutMs: Long = 6000): Boolean	Background	True only on DISCONNECTED	Lifecycle
stopAutoReconnect(reason: String): Boolean	Stop SDK reconnect	False if unavailable; does not replace disconnect	Lifecycle
forceResetDisconnected(reason: String, clearLastRequestedDevice: Boolean = true): Unit	Advanced inconsistent-state recovery	Clears local tracking/ready/AT	Lifecycle
getConnectedDevice(): XTalkDevice?	Current device	null when disconnected	State
getConnectionState(): DeviceEventState	State snapshot	Immediate	State
hasActiveBleLink(): Boolean	Physical CONNECTED gate	Does not imply Auth/Init	State
getDeviceLongId(): Long? / awaitDeviceLongId(timeoutMs: Long = 3000): Long?	Authenticated structured DID	Wait form is background; null on disconnect/deadline	Auth
isWirelessReady(): Boolean / awaitWirelessReady(timeoutMs: Long = 4000): Boolean	Init state	Wait form is background	Init
isReadyForSend(): Boolean	Business gate	CONNECTED + wireless ready	Workflow
markWirelessInitRequired(reason: String, resetAtMode: Boolean = true): Unit	Invalidate stale Auth/Init	Clears ready	Auth
setWirelessInitReady(ready: Boolean, reason: String): Unit	Auth/Init integration state	Business code must not forge true	Init

XTalkBleClient: AT, radio, advanced state

Full signature	Contract/result/thread	Example
isAtXorEnabled(): Boolean	Current connection encoding	Encoding
setAtXorEnabledForConnection(enabled: Boolean, reason: String): Unit	Advanced Auth adapter; resets on connect/disconnect	Encoding
chooseAtXorModeByFreqProbeResult(timeoutMs: Long = 1500, log: Boolean = true): AtXorModeProbeResult?	Background probe; null on unavailable/deadline	Encoding
withWirelessOpLock(block: () -> T): T	Background serialization; propagates block exception; no recursive waiting	Raw AT
runAtCommand(command: String, timeoutMs: Long = 3000, log: Boolean = true, errorPolicy: BleAtErrorPolicy = FAIL_FAST, stopWhen: ((List<String>) -> Boolean)? = null, drainResponseTailAfterStop: Boolean = false): List<String>	Exclusive/background; link/service/send/error/deadline may throw	Raw AT
sendAtCommand(command: String): SendResult	Submission result, no lines	Raw AT
sendAtCommandNoWait(command: String): Boolean	Submission only	Raw AT
sendEncryptedAt(bytes: ByteArray): Boolean	Advanced pre-encoded bytes; submission only	Raw AT
setPassthroughListener(listener: ((ByteArray) -> Unit)?): Unit	Advanced single owner; null releases; conflicts with AT transactions	Raw AT
restoreTextPttDefaults(defaultRateMode: Int = 7, defaultAddtl: Int = 1, defaultWorkMode: Int = 21): Boolean	Background; true only if all AT commands succeed	Radio
setRateMode(rateMode: Int): Boolean	Coerces 0..255; background	Radio
setChannelFrequency(freqHz: Long, timeoutMs: Long = 3000): Boolean	Callback-based channel config; background	Radio
setFrequencyHz(freqHz: Long, timeoutMs: Long = 3000): Boolean	AT sets four slots; background	Radio
setRealtimeWorkModeOverride(workMode: Int?): Unit / getRealtimeWorkModeOverride(): Int?	Session override; null clears	Voice

AtXorModeProbeResult has useXor and normalFreqAccepted. BleAtErrorPolicy is FAIL_FAST or COLLECT_UNTIL_COMPLETE.

XTalkBleClient: business, media, and device

Full signature	Return/lifecycle	Example
sendBinaryFrame(data: ByteArray): SendResult	Normal binary; background	Binary
sendRfPayloadAndWaitSendFinish(rawPayload: ByteArray, timeoutMs: Long): Boolean	Completion wait; false on error/deadline	RF
sendRfPayloadNoWait(rawPayload: ByteArray): Boolean	Realtime submission; caller rate-limits	RF
sendText(text: String): SendResult	Receive through text listener	Text
sendFile(fileBytes: ByteArray): SendResult	Completion through FileSend callback	File
cancelFileSend(): SendResult / cancelFileReceive(): SendResult	Cancellation request	File
startPttVoiceCapture(enablePcmCallback: Boolean = true): CaptureStartResult / stopPttVoiceCapture(): CaptureStopResult	Recording permission; lifecycle pair	Voice
startRealtimeVoiceCapture(peopleCount: Int = 2, mute: Int = 0): CaptureStartResult / stopRealtimeVoiceCapture(): CaptureStopResult	Recording permission; lifecycle pair	Voice
stopVoiceCaptureLocal(): CaptureStopResult	Local abnormal cleanup	Voice
startVoicePlayback(pcm: ByteArray): PlaybackStartResult / stopVoicePlayback(): PlaybackStopResult	Delivered PCM format; lifecycle pair	Playback
transcodeImage(imageBytes: ByteArray, targetTier: ImageTargetTier, inputFormat: ImageInputFormat? = null): ImageTranscodeResult	Offline; large input off-main	Image
setCryptoKey16(key16: ByteArray): Boolean	Exactly 16 bytes	Key
getHardwareVersion(timeoutMs: Long = 2000): String?	Background/cache/null failure	Queries
getFirmwareVersion(timeoutMs: Long = 2000): String?	Same	Queries
getBatteryLevel(timeoutMs: Long = 4000): Int?	Background/cache/null failure/unsupported	Queries

Listener pairs

Add/remove	Callback/thread/data rule
addDataListener / removeDataListener	bytes/len/SNR/RSSI; I/O thread; consume only len
addDeviceManageListener / removeDeviceManageListener	type/value; main-thread fanout
addTextListener / removeTextListener	source/text/metrics; main-thread fanout
addVoiceListener / removeVoiceListener	remote PCM; realtime thread
addVoiceCaptureListener / removeVoiceCaptureListener	local PCM; main-thread fanout
addFileSendListener / removeFileSendListener	send progress; main-thread fanout
addFileReceiveListener / removeFileReceiveListener	receive progress/final bytes; main-thread fanout

Top-level BLE utilities

requiredBluetoothPermissions, requiredStartupPermissions, hasBluetoothPermissions, hasStartupPermissions, sanitizeBleDeviceName, isSupportedBleDeviceName, isSupportedBleDevice, bleDeviceDisplayName, mergeBleDeviceIdentity, and XTALK_SCAN_UUID_5632G are fully described in Setup and BLE Connection.

Other modules

• Transport types, methods, Router, bridge, listeners, and advanced parsers: RadioTransport.
• Auth transport, Result, and all six operations: Auth complete contract.
• Init transport, models, and every operation: Init complete contract.
• Symbol-by-symbol audit: API Coverage Matrix.

Errors and FAQ