iOS Errors and FAQ
SDK Version: 1.0.0
Platform: iOS
BLE errors
| Error | Recommended action |
|---|---|
bluetoothUnavailable | Ask the user to enable Bluetooth, then scan again |
permissionDenied | Direct the user to Settings; do not loop permission prompts |
scanFailed(String) | Record the reason and retry after checking Bluetooth state |
deviceNotFound(UUID) | Scan again and select a current result |
deviceMismatch(String) | Stop the business flow and check device/firmware compatibility |
connectionFailed(String) | Reconnect and authenticate again |
serviceMissing / characteristicMissing | Treat the device as incompatible and stop integration |
notConnected | Reconnect |
notReady | Wait for atReady; do not send after a fixed blind delay |
busy | Serialize work; avoid concurrent no-wait/AT operations |
timeout | Check the latest connection state and reconnect if needed |
writeFailed(String) | Do not reuse an ambiguous transaction; reconnect |
cancelled | Handle as normal cancellation |
malformedResponse(String) | Preserve the response and stop the current upper-layer flow |
deviceControlFailed(String) | Degrade battery/version to unavailable; reconnect if persistent |
Auth errors
| Error | Recommended handling |
|---|---|
busy | Wait for the active authentication; do not start a concurrent one |
invalidConfiguration | Make every timeout and retry count greater than zero |
transportUnavailable | Verify the same device is connected and atReady == true; reconnect if needed |
commandTimedOut(String) | Record the command category and retry only after restoring a clean channel |
secureRandomUnavailable | Stop authentication; never downgrade to weak randomness |
invalidChallenge | Stop authentication and escalate an SDK/system issue |
challengeMissing | Device did not return a complete signature; reconnect before retrying |
malformedChallengeReply | Response violates the protocol; check device firmware compatibility |
invalidSignatureLength(Int) | Reject authentication and record the actual signature length |
signatureVerificationFailed | Reject the device from protected business flow |
challengeRetryExhausted | Challenge results remained inconsistent; reconnect before one controlled retry |
invalidDeviceIdentity | DID/SN response is invalid; reject business entry |
cancelled | Treat page exit, device switch, or explicit cancellation as normal completion |
Authentication errors fail closed. Do not continue business operations after a failure. Recover a clean transport channel, reconnect, and authenticate again.
Recommended recovery decision
Permission/Bluetooth off → user action, then scan again
Device missing/link lost → clear identity, scan, connect, authenticate
notReady → wait for state; stop when state becomes failed
busy → wait for the active transaction; do not spin-retry
timeout/write/channel failure → disconnect, reconnect, authenticate again
invalid signature/DID → fail closed; authentication cannot be bypassed
cancelled → no error alert; finish the lifecycle normally
FAQ
The link is connected but atReady stays false
The required characteristics, write capability, or notification subscription are not ready. Observe connectionState; if it changes to .failed, handle the associated error. Do not send AT early.
Why must .recoverableEncodingProbe not return early?
A late response from the wrong encoding can contaminate the next encoding probe. The transport must cover the full window and restore a clean channel after an ambiguous failure.
How should a screen be cleaned up?
Cancel authentication and event tasks, call authenticator.cancel(), remove observers, and finally call ble.teardown(). For a temporary disconnect while retaining the client, call only disconnect().
Why is there no iOS Init page?
SDK 1.0.0 has no independent iOS Device Init product. Post-auth parameter initialization belongs to the customer business layer or another separately delivered product; it must not be placed in the Auth API.
Battery or version returns nil
Check deviceControlReady first. These degradable APIs convert timeout, disconnection, or device-control response errors to nil. Reconnect on persistent failure. Do not interpret nil as zero battery or an empty version.
The same event arrives twice
The app is usually consuming events, onEvent, and observers together. Select one primary event path. Keep a fine-grained observer only for a separate purpose and remove it with its returned UUID token.
When must the app authenticate again?
Authenticate after the first connection, reconnect after link loss, device switch, and any new channel established after authentication failure. Never carry identity state from another device or connection session.