Android 错误码与常见问题
SDK Version: 1.0.0
Platform: Android
SDK 返回枚举名、异常或 reason 字符串；本文不定义未公开的数字错误码。
Auth reason
| reason | 含义 | 建议处理 |
|---|---|---|
ok | 认证和 DID 读取成功 | 进入 Init |
not_connected | 等待 BLE 连接失败 | 检查状态并重连 |
ble_not_ready | GATT/AT 通道未就绪 | 等待就绪；超时后断开重连 |
at_path_unavailable | 明文/XOR 探测都没有有效响应 | 检查设备、固件和链路 |
challenge_command_failed | Challenge 命令发送或执行失败 | 确认没有并发 AT，重试认证 |
challenge_verify_failed | Challenge 响应验签失败 | 不允许继续业务；重新连接后重试 |
did_read_failed | AT+EFUSESN?/AT+SN? 未得到有效 DID | 检查固件和设备身份数据 |
Init reason
| reason | 含义 | 建议处理 |
|---|---|---|
ok | 配置已应用 | 继续业务 |
no_vendor_config | 当前主机无需厂家配置 | 正常继续 |
missing_did | 缺少认证 DID | 返回 Auth 重新认证 |
command_no_ok | AT 响应没有 OK | 保留响应摘要，确认连接后重试 |
command_failed | AT 通道抛异常或发送失败 | 断开重连，再执行 Auth → Init |
常见问题
扫描不到设备
确认系统蓝牙已开启、运行时权限已授予、设备正在广播，并使用 XTALK_SCAN_UUID_5632G。Android 11 及以下还需要定位权限和系统定位开关。
CONNECT_OK 后仍然不能发送
CONNECT_OK 不是业务就绪。必须等待 GATT 就绪，然后完成 Auth 和 Init；最后检查 XTalkBleClient.isReadyForSend()。
AT 命令超时
不要在主线程调用，不要与 Auth、Init、OTA 或其他 AT 操作并发。确认 awaitBleReady() 成功，并把超时异常类型和已收到的响应摘要提供给技术支持。
重连后偶发认证失败
先清理旧监听器和业务任务，断开后等待 DISCONNECTED，重新连接；设备重启或 OTA 后使用 forceReauth = true。
Release 正常安装但启动崩溃
优先检查交付清单中的全部 AAR/依赖是否齐全，以及 R8 规则是否被客户工程覆盖。请提供完整异常堆栈，不要只提供“初始化失败”。
如何释放资源
停止扫描，取消业务协程，移除所有监听器，再调用 disconnect()。不要在不同页面重复注册同一个业务监听器而不移除。